ToggleGroup

ToggleGroup은 여러 Toggle을 그룹화하여 온/오프 상태를 관리하는 컴포넌트입니다. 단일 선택과 다중 선택 모드를 모두 지원합니다.

Variants

Sizes

S/Msingle/multi

Mode

Radix

Base

Playground

미리보기

outlineD40px / 14pxIcon 16px

Type

Variant

Size

Radius

Direction

State

Label

Weight

<ToggleGroup type="single" variant="outline" defaultValue="grid">
  <ToggleGroup.Item value="grid" aria-label="Grid view">
    <LayoutGrid />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="list" aria-label="List view">
    <List />
  </ToggleGroup.Item>
</ToggleGroup>

Types

Single

하나만 선택 가능, 텍스트 정렬 등 단일 선택에 사용

Multiple

여러 항목을 동시에 선택 가능, 텍스트 서식처럼 동시 적용하는 옵션에 사용

Variants

Default

경계선 없는 심플한 스타일, 툴바에 적합

Outline

그룹감을 명확히 표현하는 테두리 연결 스타일

Sizes

Icon Only

xs

높이28px

가로 패딩10px

아이콘14px

sm

높이32px

가로 패딩12px

아이콘14px

md

높이36px

가로 패딩14px

아이콘16px

default

높이40px

가로 패딩16px

아이콘16px

lg

높이48px

가로 패딩24px

아이콘16px

Size	높이	가로 패딩	아이콘
`xs`	28px	10px	14px
`sm`	32px	12px	14px
`md`	36px	14px	16px
`default`	40px	16px	16px
`lg`	48px	24px	16px

Icon + Text

xs

높이28px

가로 패딩10px

Gap4px

아이콘14px

폰트12px

sm

높이32px

가로 패딩12px

Gap8px

아이콘14px

폰트13px

md

높이36px

가로 패딩14px

Gap8px

아이콘16px

폰트14px

default

높이40px

가로 패딩16px

Gap8px

아이콘16px

폰트14px

lg

높이48px

가로 패딩24px

Gap8px

아이콘16px

폰트16px

Size	높이	가로 패딩	Gap	아이콘	폰트
`xs`	28px	10px	4px	14px	12px
`sm`	32px	12px	8px	14px	13px
`md`	36px	14px	8px	16px	14px
`default`	40px	16px	8px	16px	14px
`lg`	48px	24px	8px	16px	16px

Features

Use Cases

Grid / List 보기 전환

Finder, Dropbox, 이커머스 상품 목록

Row / Column 레이아웃

Figma, Framer, Flexbox 방향 전환

Card / Compact / Detail

Gmail, Notion, 작업 관리 앱

// Grid/List toggle - Finder, Dropbox style
<ToggleGroup type="single" variant="outline" defaultValue="grid">
  <ToggleGroup.Item value="grid" aria-label="Grid view">
    <LayoutGrid />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="list" aria-label="List view">
    <List />
  </ToggleGroup.Item>
</ToggleGroup>

// Row/Column layout - Figma, Framer style
<ToggleGroup type="single" variant="outline" defaultValue="rows">
  <ToggleGroup.Item value="rows" aria-label="Rows">
    <Rows />
  </ToggleGroup.Item>
  <ToggleGroup.Item value="columns" aria-label="Columns">
    <Columns />
  </ToggleGroup.Item>
</ToggleGroup>

// Card/Compact/Detail - Gmail, Notion style
<ToggleGroup type="single" variant="outline" defaultValue="card">
  <ToggleGroup.Item value="card" aria-label="Card view"><Grid /></ToggleGroup.Item>
  <ToggleGroup.Item value="compact" aria-label="Compact view"><List /></ToggleGroup.Item>
  <ToggleGroup.Item value="detail" aria-label="Detail view"><Rows /></ToggleGroup.Item>
</ToggleGroup>

States

Default

기본 상태. 선택된 아이템이 강조 표시됩니다.

Disabled

모든 아이템이 비활성화된 상태

개별 Disabled

특정 아이템만 비활성화

다중 선택

여러 아이템을 동시에 선택할 수 있습니다.

Orientation

Horizontal (기본값)

Vertical

API

Component Structure

ToggleGroup— Radix ToggleGroup

.ItemProps

.ItemProps토글 아이템

Props

ToggleGroup

type—

"single" | "multiple"

단일 선택 또는 다중 선택 모드

valueundefined

string | string[]

제어 모드에서의 선택 값

defaultValueundefined

string | string[]

비제어 모드에서의 초기 선택 값

onValueChangeundefined

(value) => void

선택 변경 시 호출되는 콜백

variant"default"

"default" | "outline"

아이템의 시각적 스타일

size"default"

"xs" | "sm" | "md" | "default" | "lg"

아이템 크기 (28/32/36/40/48px)

radius"default"

"none" | "sm" | "base" | "default" | "lg" | "xl" | "2xl" | "3xl" | "full"

모서리 둥글기 크기 (6px)

fontWeight"normal"

"normal" | "semibold"

폰트 굵기. 모든 아이템에 적용. 개별 아이템의 fontWeight로 덮어쓸 수 있음

orientation"horizontal"

"horizontal" | "vertical"

레이아웃 방향

disabledfalse

boolean

모든 아이템 비활성화

Name	Type	Default	Description
`type`	`"single" \| "multiple"`	`—`	단일 선택 또는 다중 선택 모드
`value`	`string \| string[]`	`undefined`	제어 모드에서의 선택 값
`defaultValue`	`string \| string[]`	`undefined`	비제어 모드에서의 초기 선택 값
`onValueChange`	`(value) => void`	`undefined`	선택 변경 시 호출되는 콜백
`variant`	`"default" \| "outline"`	`"default"`	아이템의 시각적 스타일
`size`	`"xs" \| "sm" \| "md" \| "default" \| "lg"`	`"default"`	아이템 크기 (28/32/36/40/48px)
`radius`	`"none" \| "sm" \| "base" \| "default" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "full"`	`"default"`	모서리 둥글기 크기 (6px)
`fontWeight`	`"normal" \| "semibold"`	`"normal"`	폰트 굵기. 모든 아이템에 적용. 개별 아이템의 fontWeight로 덮어쓸 수 있음
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	레이아웃 방향
`disabled`	`boolean`	`false`	모든 아이템 비활성화

ToggleGroup.Item

value—

string

아이템의 고유 값

disabledfalse

boolean

해당 아이템만 비활성화

variantinherit

"default" | "outline"

이 아이템의 variant 개별 재정의

sizeinherit

"xs" | "sm" | "md" | "default" | "lg"

이 아이템의 size 개별 재정의

radiusinherit

"none" | "sm" | ... | "full"

이 아이템의 radius 개별 재정의

fontWeightinherit

"normal" | "semibold"

이 아이템의 fontWeight 개별 재정의

Name	Type	Default	Description
`value`	`string`	`—`	아이템의 고유 값
`disabled`	`boolean`	`false`	해당 아이템만 비활성화
`variant`	`"default" \| "outline"`	`inherit`	이 아이템의 variant 개별 재정의
`size`	`"xs" \| "sm" \| "md" \| "default" \| "lg"`	`inherit`	이 아이템의 size 개별 재정의
`radius`	`"none" \| "sm" \| ... \| "full"`	`inherit`	이 아이템의 radius 개별 재정의
`fontWeight`	`"normal" \| "semibold"`	`inherit`	이 아이템의 fontWeight 개별 재정의

Customization

모든 아이템은 디자인 시스템 간격 규칙 기반의 기본값을 사용합니다. 그룹의className으로 모든 아이템을 일괄 커스터마이즈할 수 있습니다.

가로 패딩 변경

className="[&>button]:px-10"

Icon Only 너비 변경

className="[&>button]:aspect-auto [&>button]:px-5"

Tip：기본값은 일관성을 유지하도록 설계되어 있습니다. 필요한 경우에만 커스터마이즈하세요.

Anatomy

Root

그룹 컨테이너

Toggle Item

개별 토글 버튼

Active Item

현재 선택된 아이템

Best Practices

✓

권장

✓단일 선택에는 type="single" 사용
✓다중 선택에는 type="multiple" 사용
✓각 아이템에 aria-label 설정
✓관련 옵션끼리 그룹화

지양

✗아이템을 5개 이상 포함하지 않기
✗관련 없는 옵션 섞지 않기
✗내비게이션에는 사용하지 않기 (→ Tabs)
✗단일 선택에 Segmented 대신 사용하지 않기

Accessibility

키보드 조작

Tab그룹으로 포커스 이동

Space아이템 온/오프 전환

Enter아이템 온/오프 전환

←→↑↓

아이템 간 이동

ARIA

role="group" 자동 적용
aria-pressed 자동 적용
data-orientation 자동 적용
aria-label 권장

ToggleGroup vs ButtonGroup

겉모습은 비슷하지만 용도와 동작이 다릅니다. 적절한 컴포넌트를 선택하세요.

용도

ToggleGroup: 온/오프 상태 관리

ButtonGroup: 액션 버튼 그룹화

상태 관리

ToggleGroup: 자동 (Radix 관리)

ButtonGroup: 수동 (selected prop)

선택 모드

ToggleGroup: single / multiple

ButtonGroup: 수동 제어만

값 관리

ToggleGroup: value / onValueChange

ButtonGroup: 없음

사용 사례

ToggleGroup: 텍스트 정렬, 서식

ButtonGroup: 페이지네이션, 툴바

특징	ToggleGroup	ButtonGroup
용도	온/오프 상태 관리	액션 버튼 그룹화
상태 관리	자동 (Radix 관리)	수동 (selected prop)
선택 모드	single / multiple	수동 제어만
값 관리	value / onValueChange	없음
사용 사례	텍스트 정렬, 서식	페이지네이션, 툴바

선택 상태를 유지하려면 ToggleGroup, 클릭 시 액션을 실행하려면 ButtonGroup을 사용하세요.

ToggleGroup

Playground

Types

Variants

Sizes

Icon Only

Icon + Text

Features

Use Cases

States

Default

Disabled

개별 Disabled

다중 선택

Orientation

Horizontal (기본값)

Vertical

API

Component Structure

Props

ToggleGroup

ToggleGroup.Item

Customization

가로 패딩 변경

Icon Only 너비 변경

Anatomy

Best Practices

권장

지양

Accessibility

키보드 조작

ARIA

ToggleGroup vs ButtonGroup

Related

Toggle

Segmented

ButtonGroup