Components

Toggle

Docs

Toggle API 사용가이드입니다. 조합 예시는 Overview를 참고하세요.

API

단일 Toggle 스위치입니다. value · defaultValue · onValueChange는 boolean이며 true=On, false=Off입니다. Select/Radio의 value/onValueChange 패턴과 동일합니다.

import { Toggle } from "@/components/toggle";
import { Label } from "@/components/label";

const [enabled, setEnabled] = useState(false);

{/* 비제어 — defaultValue true = 초기 On. 좌·우 레이블 없음 */}
<Toggle defaultValue name="notify" />

{/* 상단 타이틀 — Label + htmlFor 권장 */}
<div className="flex flex-col gap-[var(--gap-8)]">
  <Label htmlFor="marketing">마케팅 알림</Label>
  <Toggle id="marketing" name="marketing" />
</div>

{/* 좌·우 레이블 — 필요할 때만 전달 */}
<Toggle
  value={enabled}
  onValueChange={setEnabled}
  onLabel="On"
  offLabel="Off"
/>

{/* 크기 — medium(기본) 32/16 · large 50/24 */}
<Toggle size="medium" defaultValue />
<Toggle size="large" defaultValue />

{/* On 색 커스텀 — Pagination selectedClassName과 동일 */}
<Toggle defaultValue selectedClassName="bg-emerald-500" />
<Toggle defaultValue selectedClassName="bg-[var(--status-success)]" />
<Toggle defaultValue selectedClassName="bg-[#10b981]" />
<Toggle defaultValue selectedClassName="bg-[rgba(239,68,68,0.9)]" />

{/* Disabled — disabled만 (기본 Off) */}
<Toggle disabled />

{/* Selected + Disabled — defaultValue + disabled */}
<Toggle defaultValue disabled />

Props

Name	Type	Default	Description
`size`	`"medium" \| "large"`	`"medium"`	스위치 크기. medium은 트랙 너비 32·썸 16×16, large는 트랙 너비 50·썸 24×24.
`value`	`boolean`	—	제어 모드 상태. true = On, false = Off. onValueChange와 함께 사용합니다.
`selectedClassName`	`string`	—	On일 때 트랙 className. 미전달 시 primary. Tailwind·토큰·arbitrary(hex/rgba) 모두 가능. Pagination selectedClassName과 동일 패턴.
`disabled`	`boolean`	—	비활성화. disabled만이면 Disabled(Off). defaultValue와 함께면 Selected + Disabled(muted).
`name`	`string`	—	폼 제출 시 필드 키.
`inputValue`	`string`	`"on"`	폼 제출 문자열(켜졌을 때만). boolean value와 구분해 사용합니다.
`onLabel / offLabel`	`ReactNode`	—	좌·우 레이블. 미전달 시 표시하지 않습니다. 상단 타이틀은 Label 컴포넌트(+ htmlFor)를 권장합니다.
`showLabels`	`boolean`	`true`	false면 onLabel/offLabel이 있어도 좌·우 레이블을 숨깁니다. 전달된 레이블만 표시하는 것이 기본입니다.
`className`	`string`	—	루트(label) 추가 클래스. 레이아웃용 (예: mr-auto).

Events

Name	Signature	Description
`onValueChange`	`(value: boolean) => void`	상태가 바뀔 때 호출됩니다. true = On, false = Off.
`onChange`	`(event: ChangeEvent<HTMLInputElement>) => void`	native checkbox onChange (필요 시).

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx.
clsx 패키지가 필수입니다. className 병합에 import { clsx } from "clsx" 를 사용합니다.
value/defaultValue/onValueChange의 boolean은 true=On, false=Off입니다.
size 기본값은 medium(트랙 32 · 썸 16). large는 트랙 50 · 썸 24입니다.
좌·우 onLabel/offLabel은 기본 없음. 상단 타이틀은 @/components/label 의 Label + htmlFor를 권장합니다.
On 색 기본은 primary. 커스텀은 selectedClassName(bg-emerald-500 · bg-[var(--…)] · bg-[#hex] · bg-[rgba(…)]).
disabled만이면 Disabled(Off). Selected + Disabled는 defaultValue + disabled입니다 (Checkbox/Radio와 동일).
native <input type="checkbox" role="switch"> 기반입니다.