7onicDESIGN SYSTEM

Toggle

Toggle은 ON/OFF 두 상태를 전환하는 버튼입니다. 단독으로 사용하거나 ToggleGroup으로 그룹화하여 사용합니다.

4
Variants
5
Sizes
on/off
States
Radix
Base

Playground

미리보기
defaultD
Variant
Size
Radius
Icon
Label
Weight
State
const [starred, setStarred] = useState(false)

<Toggle
  pressed={starred}
  onPressedChange={setStarred}
  iconOnly
  aria-label={starred ? "Unstar" : "Star"}
>
  <Star
    className={`transition-colors ${
      starred ? "fill-yellow-500 text-yellow-500" : ""
    }`}
  />
</Toggle>

Variants

Default
누르면 배경이 변하는 심플한 스타일, 툴바에 적합
Outline
상태를 명확히 표시하는 테두리 스타일
Ghost
아이콘 색상으로만 상태를 표현, 좋아요 버튼 등에 적합
Outline Ghost
경계는 명확하되 아이콘 색상으로만 상태 표현

Sizes

Icon Only (iconOnly=true)

xs
크기28px × 28px
아이콘14px
sm
크기32px × 32px
아이콘16px
md
크기36px × 36px
아이콘16px
default
크기40px × 40px
아이콘20px
lg
크기48px × 48px
아이콘24px

Icon + Text (iconOnly=false)

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

States

Off
On
Disabled
Disabled On
<Toggle iconOnly variant="outline" aria-label="Off"><Star className="icon-xl" /></Toggle>
<Toggle iconOnly variant="outline" defaultPressed aria-label="On"><Star className="icon-xl fill-yellow-500 text-yellow-500" /></Toggle>
<Toggle iconOnly variant="outline" disabled aria-label="Disabled"><Star className="icon-xl" /></Toggle>
<Toggle iconOnly variant="outline" disabled defaultPressed aria-label="Disabled on"><Star className="icon-xl fill-yellow-500 text-yellow-500" /></Toggle>

API

Props

pressedundefined
boolean

제어 모드의 ON/OFF 상태

defaultPressedfalse
boolean

비제어 모드의 초기 상태

onPressedChangeundefined
(pressed: boolean) => void

상태 변경 시 콜백

variant"default"
"default" | "outline" | "ghost" | "outline-ghost"

시각 스타일. ghost/outline-ghost는 배경 변화 없음 (아이콘 색상만 변경)

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"

폰트 두께. normal=400, semibold=600

iconOnlyundefined
boolean

아이콘 전용 모드. 정사각형으로 IconButton과 같은 크기 규칙 적용

pressEffectundefined
boolean

프레스 이펙트 (active:scale-pressed). 미지정 시 true로 동작. false로 비활성화

disabledfalse
boolean

비활성 상태

asChildfalse
boolean

Slot으로 렌더링

Anatomy

1
2
3
Favorite
statedata-[state=on/off]
1
Container
토글 버튼 본체
2
Icon
선택 사항
3
Label
선택 사항

Best Practices

✓

권장

  • ✓명확한 ON/OFF 상태를 시각적으로 표시
  • ✓aria-label로 목적 설명
  • ✓즉시 효과가 반영되는 조작에 사용
  • ✓여러 토글은 ToggleGroup으로 그룹화
✕

지양

  • ✗제출이 필요한 폼 항목에 사용하지 않기
  • ✗상태가 알기 어려운 아이콘 사용하지 않기
  • ✗aria-label 없이 사용하지 않기
  • ✗단일 선택에는 Segmented 사용

Accessibility

키보드 조작

Space토글 전환
Enter토글 전환

ARIA 속성

  • aria-pressed 자동 부여
  • data-state on/off
  • 포커스 인디케이터
  • aria-label 권장