ToggleGroup

하나의 상태를 공유하는 토글 묶음입니다. 이웃과 맞닿는 모서리는 각지고, 값은 세트가 소유하며, 공통 prop은 구성원 전체에 한 번만 지정합니다.

import { Toggle, ToggleGroup } from 'neba';

<ToggleGroup aria-label="Text alignment" defaultValue={['left']}>
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
  <Toggle value="right">Right</Toggle>
</ToggleGroup>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	—	세트 안의 모든 토글에 적용됩니다. 지정하지 않으면 Toggle 자신의 기본값이 그대로 쓰입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	—	세트 안의 모든 토글의 높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	—	세트 안의 모든 토글의 색 역할. 토글 하나가 자기 색을 따로 지정하면 그쪽이 이깁니다
density공통	'default' | 'compact'	—	세트 안의 모든 토글의 가로 여백
elevation공통	0 | 1 | 2 | 3	—	세트 안의 모든 토글의 그림자 깊이
value	readonly string[]	—	켜져 있는 토글들의 value. 단일 선택이든 다중 선택이든 배열입니다
defaultValue	readonly string[]	—	처음에 켜져 있는 값들 (uncontrolled)
onValueChange	(value: string[]) => void	—	값이 바뀔 때마다 호출됩니다
multiple	boolean	false	동시에 여러 개를 켤 수 있는지 여부. 꺼져 있으면 하나를 켤 때 직전 것이 꺼집니다
orientation공통	'horizontal' | 'vertical'	'horizontal'	토글이 이어지는 방향. 세로면 위아래 모서리가 깎입니다
disabled	boolean	—	세트 전체를 한 번에 비활성화합니다
loopFocus	boolean	true	방향키가 양 끝에서 순환할지 여부
fullWidth	boolean	false	컨테이너 너비만큼 확장하고 토글이 너비를 균등하게 나눠 가집니다
children	ReactNode	—	Toggle들. 중간에 다른 요소로 감싸도 세트의 값은 전달됩니다

<div>의 모든 속성이 그대로 전달됩니다. variant, size, color, density, elevation, disabled는 세트 안의 모든 Toggle에 전달되며, 토글 자신의 prop이 우선합니다. 중립적인 세트 안에 danger 토글 하나를 두는 것은 흔한 구성입니다.

예시

value와 onValueChange

값은 단일 선택이든 다중 선택이든 배열입니다. multiple을 켜도 타입이 바뀌지 않습니다. value와 onValueChange로 controlled, defaultValue로 uncontrolled 세트가 됩니다.

multiple

기본값인 false에서는 하나를 켜면 직전 것이 꺼집니다. 고르는 대상이 상태의 묶음이 아니라 값 하나라면 SegmentedButton이나 RadioGroup이 그 사실을 말해주는 컴포넌트입니다.

import { useState } from 'react';
import { Toggle, ToggleGroup } from 'neba';

export default function ToggleGroupMultiple() {
  const [marks, setMarks] = useState<readonly string[]>(['bold']);

  return (
    <div className="flex flex-col items-center gap-4">
      <ToggleGroup multiple aria-label="Marks" value={marks} onValueChange={setMarks}>
        <Toggle value="bold">Bold</Toggle>
        <Toggle value="italic">Italic</Toggle>
        <Toggle value="underline">Underline</Toggle>
      </ToggleGroup>

      <p className="text-[0.75rem] text-(--neba-muted-fg)">
        {marks.length > 0 ? marks.join(', ') : 'none'}
      </p>
    </div>
  );
}

variant

세트의 variant가 안의 모든 토글에 닿습니다.

import { Toggle, ToggleGroup } from 'neba';

const variants = ['solid', 'outline', 'text'] as const;

export default function ToggleGroupVariants() {
  return (
    <div className="flex flex-col items-center gap-5">
      {variants.map((variant) => (
        <ToggleGroup key={variant} aria-label={variant} variant={variant} defaultValue={['week']}>
          <Toggle value="day">Day</Toggle>
          <Toggle value="week">Week</Toggle>
          <Toggle value="month">Month</Toggle>
        </ToggleGroup>
      ))}
    </div>
  );
}

orientation

vertical은 토글을 세로로 쌓고 가로 이음매 쪽 모서리를 각지게 만듭니다. 방향키도 방향을 따릅니다.

import { Toggle, ToggleGroup } from 'neba';

export default function ToggleGroupOrientation() {
  return (
    <ToggleGroup orientation="vertical" aria-label="Density" defaultValue={['cosy']}>
      <Toggle value="compact">Compact</Toggle>
      <Toggle value="cosy">Cosy</Toggle>
      <Toggle value="roomy">Roomy</Toggle>
    </ToggleGroup>
  );
}

fullWidth

컨테이너 너비만큼 늘어나고 토글들이 그 폭을 균등하게 나눠 갖습니다.

import { Toggle, ToggleGroup } from 'neba';

export default function ToggleGroupFullWidth() {
  return (
    <div className="w-full max-w-md">
      <ToggleGroup fullWidth aria-label="View" defaultValue={['board']}>
        <Toggle value="list">List</Toggle>
        <Toggle value="board">Board</Toggle>
        <Toggle value="calendar">Calendar</Toggle>
      </ToggleGroup>
    </div>
  );
}

접근성

• 세트 전체가 하나의 tab stop입니다. 방향키로 토글 사이를 이동하고, 끝에서 순환할지는 loopFocus가 정합니다.
• 그룹 자체에는 이름이 없으므로 aria-label을 주세요.