Skip to Content
ComponentsFoundationSwitch

Switch

On/Off 상태를 전환하는 토글 스위치 컴포넌트

개요

Switch 컴포넌트는 base-ui의 Switch Primitive를 기반으로 구축된 토글 스위치입니다. 설정 변경, 기능 활성화/비활성화 등에 사용됩니다.

주요 특징

  • ✅ Sizes: xs, sm, md, lg, xl 5단계 크기
  • ✅ 제어/비제어 모드: checked와 defaultChecked 지원
  • ✅ 읽기 전용: readOnly 상태에서 상태 전환 방지
  • ✅ 접근성: base-ui 기반으로 role="switch", aria-checked 자동 적용
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

Sizes

Switch는 5가지 크기를 지원합니다. 기본값은 md입니다.

사용 예시

Label과 함께 사용

기본 체크 상태

defaultChecked로 초기 상태를 설정합니다.

비활성 상태

읽기 전용 상태

readOnly 상태에서는 사용자가 상태를 전환할 수 없지만, 현재 상태를 시각적으로 확인할 수 있습니다.

필수 선택 제어

required를 설정하면 반드시 체크(On) 상태여야 하는 스위치로 지정됩니다.

설정 목록

여러 Switch를 목록으로 배치합니다.

API Reference

Props

PropTypeDefaultDescription
size"xs" | "sm" | "md" | "lg" | "xl""md"크기
checkedboolean-제어 모드 체크 상태
defaultCheckedboolean-초기 체크 상태
onCheckedChange(checked: boolean) => void-체크 상태 변경 콜백
disabledboolean-비활성 상태
readOnlyboolean-읽기 전용 상태
requiredboolean-필수 입력 여부
namestring-폼 제출 시 필드 이름
classNamestring-추가 CSS 클래스

기본 사용법

import { Switch } from "@vortex/ui-foundation"
 
<Switch />
<Switch size="sm" />
<Switch defaultChecked />
<Switch disabled />

접근성

ARIA 속성

  • base-ui가 role="switch", aria-checked 자동 설정
  • 포커스 링 자동 적용 (focus-visible)

키보드 네비게이션

  • Space: 토글 전환
  • Tab: 포커스 이동

권장 사항

  • ✅ Label과 함께 사용하여 접근성 보장 (htmlFor와 id 연결)
  • ✅ 즉시 적용되는 설정 변경에 사용
  • ❌ 폼 제출이 필요한 경우는 Checkbox 사용 권장

관련 컴포넌트

Last updated on
StepTable