ToggleGroup

텍스트 정렬, 보기 전환, 텍스트 스타일처럼 하나의 컨트롤로 읽히는 토글 버튼 묶음입니다. ToggleGroup.Root는 role="group"이고, 각 ToggleGroup.Item은 aria-pressed가 있는 secondary Button.Root입니다. 묶음은 Tab 순서에서 한 자리를 차지하며, 그 자리는 single 모드에서는 눌린 항목, multiple 모드에서는 첫 항목입니다. 화살표 키는 항목을 누르지 않고 포커스만 옮깁니다.

기본값인 single 모드에서는 많아야 한 항목이 눌리며, 눌린 항목을 다시 누르면 값이 null이 됩니다.

<ToggleGroup.Root aria-label="Alignment" value={align} onValueChange={setAlign}>
  <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
  <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
  <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
</ToggleGroup.Root>

selectionMode="multiple"이면 몇 개든 누를 수 있고, 값은 배열입니다.

묶음에는 aria-label이나 aria-labelledby로 이름을 붙이세요. 가로 항목은 Button.Group처럼 붙습니다. Toolbar 안에서는 툴바가 화살표 키와 탭 위치를 맡습니다.

언제 쓰나

쓸 때: 무언가를 보여 주는 방식을 바꾸는 옵션으로, 눌린 상태가 한눈에 보이고 바로 적용될 때.

쓰지 않을 때: 제출하는 폼의 선택 → Radio나 Checkbox. 설정 하나를 켜고 끔 → Switch나 토글 Button.Root 하나. 콘텐츠 패널 사이 전환 → Tabs.

Props

ToggleGroup.Root props
이름	타입	필수	기본값	설명
aria-label	`string`	아니요	—	"Alignment"처럼 묶음의 이름을 붙입니다.
selectionMode	`"single" \| "multiple"`	아니요	"single"	single은 많아야 한 항목을 누르며, 다시 누르면 해제됩니다. multiple은 몇 개든 누릅니다.
value	`string \| null \| readonly string[]`	아니요	—	제어되는 눌림 값: single은 값이나 null, multiple은 배열.
defaultValue	`string \| null \| readonly string[]`	아니요	—	제어되지 않을 때의 처음 눌림 값.
onValueChange	`((value: string \| null) => void) \| ((value: string[]) => void)`	아니요	—	항목을 누르면 새 눌림 값으로 호출됩니다.
orientation	`"horizontal" \| "vertical"`	아니요	"horizontal", or the toolbar's	배치, 그리고 툴바 밖에서 포커스를 옮기는 화살표 키. 가로 항목은 Button.Group처럼 붙습니다.
disabled	`boolean`	아니요	false	모든 항목을 비활성화합니다.
children	`React.ReactNode`	아니요	—	ToggleGroup.Item 요소.

ToggleGroup.Item props
이름	타입	필수	기본값	설명
value	`string`	예	—	묶음 값에서 항목을 식별합니다.
disabled	`boolean`	아니요	false	이 항목을 비활성화합니다.
children	`React.ReactNode`	아니요	—	레이블, 또는 aria-label이 있는 Button.Icon.