ToggleGroup
상호 배타적 또는 복수 토글 버튼을 조정해요. TRToggle과 마찬가지로 자체 폼 값을 제출하지 않아요.
핵심 속성
| 항목 | 설명 |
|---|---|
| 선택 | 기본값은 0개 또는 1개이며, multiple로 여러 값을 독립적으로 선택 |
| 상태 | 제어형 value 또는 비제어형 defaultValue; 둘 다 문자열 배열을 사용하고 기본값은 [] |
| 방향 | 기본값은 가로이며 필요할 때 세로로 설정 |
| 키보드 | 방향에 맞는 화살표와 Home/End 사용; 기본적으로 순환하며 loopFocus={false}이면 끝에서 정지 |
| 사용 가능 여부 | 기본적으로 활성화되며 그룹 전체 또는 개별 항목을 비활성화 가능 |
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/toggle-group.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRToggleGroup } from '@tinyrack/ui/components/toggle-group';
import { TRToggle } from '@tinyrack/ui/components/toggle';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
API
구조
<TRToggleGroup aria-label="텍스트 정렬">
<TRToggle value="start">시작</TRToggle>
<TRToggle value="center">가운데</TRToggle>
</TRToggleGroup>TRToggleGroup은 상태와 순환 포커스를 관리하는 루트예요. 자식은 @tinyrack/ui/components/toggle에서 가져온 공개 TRToggle 컴포넌트이며, 그룹 안의 각 토글에는 안정적이고 고유한 value가 필요해요.
속성
| 속성 | 타입 | 기본값 | 용도 |
|---|---|---|---|
value | readonly string[] | - | 제어형 눌림 값이에요. |
defaultValue | readonly string[] | [] | 비제어형 눌림 값의 초기값이에요. |
onValueChange | (value, details) => void | - | 다음 배열과 네이티브 이벤트 세부 정보를 전달해요. details.cancel()로 Base UI의 내부 업데이트를 취소할 수 있어요. |
multiple | boolean | false | 각 항목을 독립적으로 전환할 수 있게 해요. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | 레이아웃과 활성 화살표 키 축을 선택해요. |
loopFocus | boolean | true | 첫 번째와 마지막 활성 항목 사이에서 화살표 키 포커스를 순환해요. |
disabled | boolean | false | 그룹의 모든 항목을 비활성화해요. |
render | ReactElement | function | <div> | 동작과 병합된 ref와 속성을 유지하면서 루트를 교체해요. |
Root는 role="group"으로 렌더링되므로 aria-label 또는 aria-labelledby를 제공하세요. 가로에서는 Left/Right, 세로에서는 Up/Down으로 포커스를 이동하고 Home/End는 첫 번째·마지막 활성 항목으로 이동해요. 비활성화된 항목은 순환 포커스에서 건너뛰어요. Group의 disabled는 모든 항목에 적용되지만 개별 TRToggle은 독립적으로 비활성화할 수 있어요.
className, style, 네이티브 div 속성, 이벤트 처리기, ref가 전달돼요. --tr-toggle-group-gap과 --tr-toggle-group-color로 간격과 텍스트 색상을 바꾸고, 토글 자체의 모양은 TRToggle 토큰으로 조정하세요. ToggleGroup은 이름 있는 폼 값을 제출하지 않으므로, 선택 값이 폼 제출에 포함돼야 한다면 TRCheckboxGroup 또는 TRRadioGroup을 사용하세요.