Component

Switch

즉시 반영되는 켜짐·꺼짐 상태를 바꿉니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

switch 옆 레이블

같은 size의 입력 필드에 맞춘 표시·레이블 크기

켜짐 상태 (defaultChecked)

비활성

Code

import { Switch } from '@amineslab/ui'

export default function ExamplePreview() {
  return ((<Switch defaultChecked={true} disabled={false} key={"true"} label={"자동 저장"} size={"md"}/>))
}

Props

@amineslab/ui에서 Switch를 가져옵니다.

import { Switch } from '@amineslab/ui'

`Switch`

HTML <button> 요소의 표준 속성을 그대로 받습니다.

Name	Type	Default	Description
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	같은 size의 입력 필드와 비례하는 표시·레이블 크기입니다. 모바일 표시는 4px 확대됩니다.
`checked`	`boolean`	-	외부에서 제어하는 켜짐 상태입니다.
`defaultChecked`	`boolean`	`false`	내부 상태로 관리할 때의 초기값입니다.
`label`	`ReactNode`	-	switch 옆에 표시할 레이블입니다.
`onCheckedChange`	`(checked: boolean) => void`	-	상태가 바뀔 때 호출합니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

Controlled

즉시 반영되는 설정이면 onCheckedChange에서 바로 저장합니다.

다크 모드

import { Switch } from '@amineslab/ui'

export default function ExamplePreview() {
  return (<Switch defaultChecked={false} label="다크 모드"/>)
}

Sizes · 입력 필드와 비교

같은 size의 입력·버튼·선택 표시·상태 표시를 나란히 비교합니다. 모바일 조작 행은 8px, Switch·Checkbox·Radio·Slider의 표시는 4px 확대됩니다.

import { type ControlSize, Input, Button, Switch, Checkbox, RadioGroup, RadioGroupItem, Badge, Spinner, Slider, Progress } from '@amineslab/ui'

const controlSizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly ControlSize[];

const sizes = controlSizes;

function RelatedControlSizes() {
    return (<div className="grid w-full gap-6">
      {sizes.map((size) => (<div key={size} className="grid gap-3 rounded-lg border border-elevation-700 p-4">
          <span className="text-label-3 text-text-secondary">{size}</span>
          <div className="flex flex-wrap items-center gap-4">
            <Input aria-label={`입력 ${size}`} placeholder="입력" size={size} className="w-32"/>
            <Button size={size}>저장</Button>
            <Switch defaultChecked label="자동 저장" size={size}/>
            <Checkbox defaultChecked label="선택" size={size}/>
            <RadioGroup defaultValue="on" aria-label={`라디오 ${size}`} size={size}>
              <RadioGroupItem value="on" label="사용"/>
            </RadioGroup>
            <Badge size={size}>완료</Badge>
            <Spinner label={`불러오는 중 ${size}`} size={size}/>
          </div>
          <div className="grid items-center gap-4 sm:grid-cols-2">
            <Slider aria-label={`범위 ${size}`} defaultValue={[50]} size={size}/>
            <Progress label={`진행률 ${size}`} value={50} size={size}/>
          </div>
        </div>))}
    </div>);
}

export default function ExamplePreview() {
  return (<RelatedControlSizes />)
}

SwitchField로 사용하기

SwitchField는 기본 입력에 label·required·description·error를 함께 제공합니다. FormStack 안에 직접 넣으며 FormField로 다시 감싸지 않습니다.

알림 수신

라벨·설명·필수 표시를 Field가 함께 처리합니다.

import { useState } from 'react'

import { SwitchField } from '@amineslab/ui'

const fieldDescription = '라벨·설명·필수 표시를 Field가 함께 처리합니다.';

function SwitchFieldExample() {
    const [value, setValue] = useState(false);
    return (<SwitchField label="알림 수신" description={fieldDescription} required value={value} onValueChange={setValue}/>);
}

export default function ExamplePreview() {
  return (<SwitchFieldExample />)
}

사용 기준

권장하는 사용

결과가 저장 버튼 없이 곧바로 적용될 때 사용합니다.

피해야 할 사용

폼 제출 전까지 반영되지 않는 값에는 checkbox를 우선합니다.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

Space: 상태 전환