ToggleSwitch

Data Input

단일 항목을 즉시 켜고 끄는 토글 스위치.

Usage

단일 항목의 켜기/끄기를 즉시 적용(폼 전송 없이). 설정·기능 on/off

import

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

예제를 복사해 쓸 때 필요한 준비

• @mildang/styled-system 은 이 저장소에서 Panda 가 생성하는 산출물이다. 저장소 안에서는 turbo run ship 이후 쓸 수 있고, 패키지 소비자는 자기 Panda 산출물이나 다른 레이아웃 수단으로 바꿔야 한다.

API Reference

ToggleSwitch Props

Prop

Type

Default

checked

boolean

지정 안 함

className

string

지정 안 함

defaultChecked

boolean

지정 안 함

description

ReactNode

지정 안 함

descriptionDirection

"horizontal" | "vertical"

horizontal

disabled

boolean

지정 안 함

string

지정 안 함

label

ReactNode

지정 안 함

labelPlacement

"left" | "right"

right

onChange

(checked: boolean) => void

지정 안 함

size

"sm" | "md"

보조 설명 배치

description 을 라벨과 함께 넣으면 descriptionDirection 으로 배치를 가로·세로로 바꿀 수 있다.

horizontal(기본) — 라벨과 한 줄에 나란히 둔다. 가로 공간이 넉넉한 데스크톱·태블릿 화면, 짧은 요약 문구에 맞다.
vertical — 라벨 아래로 내린다. 라벨이 길거나 1~2줄 보조 설명이 필요한 모바일·좁은 폭 화면, 항목이 많아 세로 스크롤이 자연스러운 목록에 맞다.

보조 설명

라벨 아래 부연 문구를 가로·세로 방향으로 배치합니다. 문구가 길면 vertical 이 읽기 편합니다.

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';
import { VStack } from '@mildang/styled-system/jsx';

export default function ToggleSwitchDescriptionExample() {
  return (
    <VStack alignItems="stretch" gap="4">
      <ToggleSwitch
        label="자동 결제"
        description="매달 같은 날짜에 자동으로 결제됩니다"
        descriptionDirection="horizontal"
        defaultChecked
      />
      <ToggleSwitch
        label="위치 기반 추천"
        description="현재 위치를 기준으로 콘텐츠를 추천합니다"
        descriptionDirection="vertical"
      />
    </VStack>
  );
}

예제

기본 사용

checked 와 onChange 로 상태를 직접 들고 있는 단일 스위치 — 설정 항목 하나를 즉시 켜고 끕니다.

코드

Open in Playground

'use client';

import { useState } from 'react';
import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

export default function ToggleSwitchBasicExample() {
  const [checked, setChecked] = useState(false);

  return <ToggleSwitch label="알림 받기" checked={checked} onChange={setChecked} />;
}

Sizes

md 와 sm 의 스위치 크기를 비교합니다. 목록 안에 여러 개가 들어가면 sm 을 씁니다.

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';
import { VStack } from '@mildang/styled-system/jsx';

export default function ToggleSwitchSizesExample() {
  return (
    <VStack alignItems="flex-start" gap="4">
      <ToggleSwitch size="md" label="md" defaultChecked />
      <ToggleSwitch size="sm" label="sm" defaultChecked />
    </VStack>
  );
}

라벨 위치

라벨을 좌우로 바꿔 비교합니다. 상태를 먼저 스캔해야 하는 목록은 스위치를 좌측에 둡니다.

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';
import { VStack } from '@mildang/styled-system/jsx';

export default function ToggleSwitchLabelPlacementExample() {
  return (
    <VStack alignItems="stretch" gap="4">
      <ToggleSwitch label="마케팅 알림" labelPlacement="left" defaultChecked />
      <ToggleSwitch label="마케팅 알림" labelPlacement="right" defaultChecked />
    </VStack>
  );
}

상태

켜짐·꺼짐 상태의 비활성화를 나란히 둡니다. 권한이 없거나 조건이 안 맞을 때 씁니다.

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';
import { VStack } from '@mildang/styled-system/jsx';

export default function ToggleSwitchStatesExample() {
  return (
    <VStack alignItems="flex-start" gap="4">
      <ToggleSwitch label="비활성 (꺼짐)" disabled />
      <ToggleSwitch label="비활성 (켜짐)" disabled defaultChecked />
    </VStack>
  );
}

IconOnly

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const ToggleSwitchIconOnlyExample = () => <ToggleSwitch size="md" />;

export default ToggleSwitchIconOnlyExample;

LabelLeft

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const ToggleSwitchLabelLeftExample = () => <ToggleSwitch label="Label on Left" labelPlacement="left" />;

export default ToggleSwitchLabelLeftExample;

LabelRight

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const ToggleSwitchLabelRightExample = () => <ToggleSwitch label="Label on Left" labelPlacement="right" />;

export default ToggleSwitchLabelRightExample;

DescriptionHorizontal

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const ToggleSwitchDescriptionHorizontalExample = () => (
    <ToggleSwitch
      label="Basic with Description"
      description="This is a description text"
      labelPlacement="right"
    />
  );

export default ToggleSwitchDescriptionHorizontalExample;

DescriptionVertical

코드

Open in Playground

import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const ToggleSwitchDescriptionVerticalExample = () => (
    <ToggleSwitch
      label="Vertical Description"
      description="This description appears vertically below"
      descriptionDirection="vertical"
      labelPlacement="right"
    />
  );

export default ToggleSwitchDescriptionVerticalExample;

Demo

코드

Open in Playground

import type { ComponentProps } from 'react';
import { ToggleSwitch, type ToggleSwitchProps } from '@mildang/design-system/ToggleSwitch';

const STORY_DEFAULT_ARGS = { ...({}), ...({
    label: 'Toggle me',
    size: 'md',
    disabled: false,
    labelPlacement: 'right',
  } satisfies ToggleSwitchProps) } as ComponentProps<typeof ToggleSwitch>;

export default function ToggleSwitchDemoExample(props: Partial<ComponentProps<typeof ToggleSwitch>> = {}) {
  const mergedProps = { ...STORY_DEFAULT_ARGS, ...props } as ComponentProps<typeof ToggleSwitch>;
  return <ToggleSwitch {...mergedProps} />;
}

Disabled

코드

Open in Playground

import type { ComponentProps } from 'react';
import { ToggleSwitch } from '@mildang/design-system/ToggleSwitch';

const STORY_DEFAULT_ARGS = { ...({}), ...({ label: 'Disabled', disabled: true }) } as ComponentProps<typeof ToggleSwitch>;

export default function ToggleSwitchDisabledExample(props: Partial<ComponentProps<typeof ToggleSwitch>> = {}) {
  const mergedProps = { ...STORY_DEFAULT_ARGS, ...props } as ComponentProps<typeof ToggleSwitch>;
  return <ToggleSwitch {...mergedProps} />;
}