Switch

설정을 즉시 켜고 끄는 컨트롤입니다. 조작하는 순간 효력이 생기는 항목에 씁니다.

import { Switch } from 'neba';

<Switch label="이메일 알림" defaultChecked />;

Props

Prop	타입	기본값	설명
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
label	ReactNode	—	컨트롤과 연결되는 라벨. Base UI Field가 묶어 줍니다
description	ReactNode	—	보조 설명
error	ReactNode	—	오류 메시지. 값이 있으면 invalid 상태도 함께 켜지고 색 계열이 danger로 넘어갑니다
invalid	boolean	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
checked	boolean	—	켜짐 여부. onCheckedChange와 함께 제어 컴포넌트로 씁니다
defaultChecked	boolean	false	초기 켜짐 여부
onCheckedChange	(checked: boolean, details) => void	—	켜고 꺼질 때
labelPlacement	'start' | 'end'	'end'	라벨이 놓이는 쪽. start는 설정 목록처럼 스위치가 오른쪽에 정렬되어야 할 때
name	string	—	폼 제출 시의 필드 이름
readOnly	boolean	false	값은 보이지만 바꿀 수 없음. 색과 가장자리는 유지한 채 채도만 빠집니다
disabled	boolean	false	사용 불가. 색 계열을 버리고 중립 회색이 됩니다
classNames	NebaSlots<'label' | 'control' | 'description' | 'error' | 'thumb'>	—	루트 뒤에 있는 각 파트의 class. 루트 자체는 className이 맡으므로 root 키는 없습니다

아래에 저장 버튼이 있어서 값이 폼과 함께 제출된다면 Checkbox를 쓰세요. 그것이 두 컴포넌트를 가르는 기준입니다.

예시

checked와 onCheckedChange

checked와 onCheckedChange로 controlled, defaultChecked로 uncontrolled 컴포넌트가 됩니다.

disabled · readOnly

import { Switch } from 'neba';

export default function SwitchStates() {
  return (
    <div className="flex flex-col gap-3">
      <Switch label="Off" />
      <Switch label="On" defaultChecked />
      <Switch label="Read-only" readOnly defaultChecked />
      <Switch label="Disabled" disabled />
      <Switch label="Disabled and on" disabled defaultChecked />
    </div>
  );
}

labelPlacement

end(기본)는 컨트롤 뒤에 라벨을 두어 설명처럼 읽히게 합니다. start는 라벨이 왼쪽 열을 이루고 스위치가 오른쪽에 정렬되는 설정 목록에 적합합니다.

import { Switch } from 'neba';

export default function SwitchPlacement() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <Switch
        labelPlacement="start"
        label="Two-factor authentication"
        description="Required for admins."
        defaultChecked
      />
      <Switch labelPlacement="start" label="Session timeout" description="After 30 minutes." />
    </div>
  );
}

size

import { Switch } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function SwitchSizes() {
  return (
    <div className="flex flex-col gap-3">
      {SIZES.map((size) => (
        <Switch key={size} size={size} label={size} defaultChecked />
      ))}
    </div>
  );
}

classNames

className은 track이 아니라 감싸는 field wrapper에 붙습니다. track과 thumb은 classNames로 갑니다.

<Switch label="Email alerts" classNames={{ control: 'w-14', thumb: 'rounded-sm' }} />

slot은 label, control, thumb, description, error입니다. control은 track(켜지면 채워지는 알약)이고 thumb은 그 위를 오가는 원입니다. 넘긴 class가 컴포넌트 자신의 class와 어떻게 겨루는지는 prop 규약을 보세요.

접근성

• role="switch"와 함께 숨은 <input>이 렌더링됩니다.
• 라벨이 컨트롤과 연결되어 있어 글자를 눌러도 전환됩니다.
• label을 쓰지 않는다면 aria-label을 주세요.
• thumb의 이동은 prefers-reduced-motion에서 즉시 전환됩니다.