Switch

한눈에#

트랙·라벨 어느 쪽을 눌러도 토글되는 즉시-적용 on/off 컨트롤입니다.

사용 시점#

켜는 즉시 적용되는 단일 on/off면 Switch — 제출 전 보류·혼합 상태면 Checkbox입니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { Switch } from '@wds/ui-web';

<Switch>다크 모드</Switch>

해부#

트랙·썸·히트 영역 위에 토큰 실측을 핀으로 얹습니다 — 썸은 장식, 진실은 aria-checked입니다.

변형#

라벨이 없으면 aria-labelledby 연결도 생략되므로 aria-label을 직접 부여해야 합니다.

크기#

size로 2단(ADR-012 B-P2) — md(기본) 44×24px 트랙 + 18px 썸, sm 36×20px 트랙

• 14px 썸. 두 크기 모두 시각 트랙과 무관하게 히트 영역이 control.height-md(44px)로 확장되어 터치 타깃을 보장합니다.

상태#

• Checked — 트랙이 color.primary로 채워지고 썸이 우측으로 이동
• Focus — 트랙 :focus-visible에 2px primary 아웃라인
• Disabled — color.surface-muted 트랙 + 커서 차단

제어 · 비제어#

checked를 넘기지 않으면 비제어 — defaultChecked로 시작해 내부 상태가 on/off를 소유합니다. checked를 넘기면 제어 — 그 값이 진실의 원천이 되고 토글은 내부 상태를 쓰지 않은 채 onChange(next)만 통지하므로, 부모가 checked를 갱신해야 시각 상태가 바뀝니다.

function Setting() {
  const [on, setOn] = useState(false);
  return (
    <Switch checked={on} onChange={setOn}>
      이메일 알림
    </Switch>
  );
}

Props#

className은 루트 label에 적용됩니다.

접근성#

• button[role="switch"] + aria-checked — 보조기술에 on/off 상태로 보고
• Space/Enter 활성화는 네이티브 button 의미론에 위임 — 별도 키 핸들러 없음
• children 라벨은 <label> 클릭 연동 + aria-labelledby로 이름 연결 — 라벨 없이 쓰면 aria-label을 부여하세요
• 썸은 장식(aria-hidden) — 상태의 진실은 aria-checked

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).