Toggle Group

켜거나 끌 수 있는 두 가지 상태의 버튼 집합이에요.

출처: 문서

본문

여러 개의 토글 버튼을 그룹으로 묶은 컴포넌트예요. 가로/세로 방향을 지원하고 단일(single) 또는 다중(multiple) 누름을 지원하며, 키보드 내비게이션을 완전히 지원해요.

Features

완전한 키보드 내비게이션.
가로/세로 방향 지원.
단일 및 다중 누름 버튼 지원.
제어(controlled)/비제어(uncontrolled) 방식 모두 지원.

Anatomy

컴포넌트를 임포트해요.

import { ToggleGroup } from "radix-ui";

export default () => (
  <ToggleGroup.Root>
    <ToggleGroup.Item />
  </ToggleGroup.Root>
);

API Reference

Root

토글 그룹의 모든 파트를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`type*`	`enum`	No default value
`value`	`string`	No default value
`defaultValue`	`string`	No default value
`onValueChange`	`function`	No default value
`value`	`string[]`	`[]`
`defaultValue`	`string[]`	`[]`
`onValueChange`	`function`	No default value
`disabled`	`boolean`	`false`
`rovingFocus`	`boolean`	`true`
`orientation`	`enum`	`undefined`
`dir`	`enum`	No default value
`loop`	`boolean`	`true`

Data attribute	Values
`[data-orientation]`	`"vertical" \| "horizontal"`

Item

그룹의 아이템이에요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`value*`	`string`	No default value
`disabled`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"on" \| "off"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

Examples

항상 값이 있도록 보장

컴포넌트를 제어해 값이 항상 있도록 할 수 있어요.

import * as React from "react";

import { ToggleGroup } from "radix-ui";

export default () => {
  const [value, setValue] = React.useState("left");

  return (
    <ToggleGroup.Root
      type="single"
      value={value}
      onValueChange={(value) => {
        if (value) setValue(value);
      }}
    >
      <ToggleGroup.Item value="left">
        <TextAlignLeftIcon />
      </ToggleGroup.Item>

      <ToggleGroup.Item value="center">
        <TextAlignCenterIcon />
      </ToggleGroup.Item>

      <ToggleGroup.Item value="right">
        <TextAlignRightIcon />
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  );
};

Accessibility

아이템 간 포커스 이동을 roving tabindex로 관리해요.

키보드 상호작용

Key	Description
`Tab`	Moves focus to either the pressed item or the first item in the group.
`Space`	Activates/deactivates the item.
`Enter`	Activates/deactivates the item.
`ArrowDown`	Moves focus to the next item in the group.
`ArrowRight`	Moves focus to the next item in the group.
`ArrowUp`	Moves focus to the previous item in the group.
`ArrowLeft`	Moves focus to the previous item in the group.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.

더 알아보기 (Learn more)

type="single"이면 하나만, type="multiple"이면 여러 아이템을 동시에 누를 수 있어요.
rovingFocus로 그룹 내 포커스 이동을 roving tabindex 방식으로 관리해요.