Switch

사용자가 체크/체크 해제 상태를 토글할 수 있게 해 주는 컨트롤이에요.

출처: 문서

본문

켜짐/꺼짐을 토글하는 스위치 컨트롤이에요. 키보드 내비게이션을 완전히 지원하고 제어/비제어 방식 모두 사용할 수 있어요. form 안에서 쓰면 폼 전송용 숨김 input도 함께 렌더링돼요.

Features

완전한 키보드 내비게이션.
제어(controlled)/비제어(uncontrolled) 방식 모두 지원.

Anatomy

모든 파트를 임포트해 조립해요.

import { Switch } from "radix-ui";

export default () => (
  <Switch.Root>
    <Switch.Thumb />
  </Switch.Root>
);

API Reference

Root

스위치의 모든 파트를 담아요. form 안에서 사용하면 이벤트 전파가 올바르게 되도록 input도 렌더링돼요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultChecked`	`boolean`	No default value
`checked`	`boolean`	No default value
`onCheckedChange`	`function`	No default value
`disabled`	`boolean`	No default value
`required`	`boolean`	No default value
`name`	`string`	No default value
`value`	`string`	`on`

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	Present when disabled

Thumb

스위치가 켜졌는지 꺼졌는지 시각적으로 나타내는 데 사용하는 썸이에요.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	Present when disabled

Examples

숨겨진 input 분리하기

기본적으로 Switch.Root는 폼 제출을 위해 시각적으로 숨겨진 input을 렌더링해요. 그 input을 재구성하거나 이동하거나 제외하려면, 더 낮은 레벨의 파트들로 스위치를 조립할 수 있어요.

중요: 이 파트들은 불안정하며 unstable_ 접두사가 붙어 있어서 API가 향후 릴리스에서 바뀔 수 있어요.

Switch.unstable_Provider는 스위치 상태를 제공하고 폼 관련 props(name, value, checked, defaultChecked, required, disabled, onCheckedChange)를 받아요.
Switch.unstable_Trigger는 Switch.Thumb을 감싸는 상호작용 버튼이에요.
Switch.unstable_BubbleInput은 Switch.Root가 기본으로 렌더링하는 시각적으로 숨겨진 input이에요. 폼 제출이 필요 없으면 생략해요.

import { Switch } from "radix-ui";

export default () => (
  <Switch.unstable_Provider name="airplane-mode">
    <Switch.unstable_Trigger>
      <Switch.Thumb />
    </Switch.unstable_Trigger>

    {/* The hidden input can be omitted if you don't need form submission */}

    <Switch.unstable_BubbleInput />
  </Switch.unstable_Provider>
);

Accessibility

switch role 요구사항을 준수해요.

키보드 상호작용

Key	Description
`Space`	Toggles the component's state.
`Enter`	Toggles the component's state.

더 알아보기 (Learn more)

폼에서 스위치 값을 전송하려면 name/value props를 지정하면 돼요(기본 value는 "on").
키보드로 Space/Enter로 상태를 토글할 수 있어요.