# Switch
URL: /lynx/components/switch
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/switch.mdx

특정 설정 및 상태를 즉시 켜거나 끌 수 있도록 하는 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6

사용 가능 버전: @seed-design/lynx-react@0.1.0, @seed-design/lynx-css@0.1.0

## Preview

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { Switch } from "@/components/ui/switch";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <view className="switch-preview">
        <Switch accessibility-label="Switch" defaultChecked />
      </view>
    </view>
  );
}
```

## Installation

- npm: npx @seed-design/cli@latest add ui:switch
- pnpm: pnpm dlx @seed-design/cli@latest add ui:switch
- yarn: yarn dlx @seed-design/cli@latest add ui:switch
- bun: bun x @seed-design/cli@latest add ui:switch

## Props

### `Switch`

### `Switchmark`

## Examples

### Sizes

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Switch, type SwitchProps } from "@/components/ui/switch";

function SwitchItem({ size, label }: { size: SwitchProps["size"]; label: string }) {
  return <Switch size={size} label={label} defaultChecked />;
}

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <VStack className="switch-preview" gap="spacingY.componentDefault">
        <SwitchItem size="32" label="32 (default)" />
        <SwitchItem size="24" label="24" />
        <SwitchItem size="16" label="16" />
      </VStack>
    </view>
  );
}
```

### Tones

#### Brand

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { Switch } from "@/components/ui/switch";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <view className="switch-preview">
        <Switch tone="brand" label="Brand" defaultChecked />
      </view>
    </view>
  );
}
```

#### Neutral

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { Switch } from "@/components/ui/switch";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <view className="switch-preview">
        <Switch tone="neutral" label="Neutral" defaultChecked />
      </view>
    </view>
  );
}
```

### Long Label

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Switch, type SwitchProps } from "@/components/ui/switch";

const label =
  "Consequat ut veniam aliqua deserunt occaecat enim occaecat veniam et et cillum nulla officia incididunt incididunt. Sint laboris labore occaecat fugiat culpa voluptate ullamco in elit dolore exercitation nulla.";

function SwitchItem({ size }: { size: SwitchProps["size"] }) {
  return <Switch size={size} label={label} />;
}

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <VStack className="switch-preview" gap="spacingY.componentDefault">
        <SwitchItem size="32" />
        <SwitchItem size="24" />
        <SwitchItem size="16" />
      </VStack>
    </view>
  );
}
```

### Disabled

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Switch, type SwitchProps } from "@/components/ui/switch";

function SwitchItem({
  disabled,
  label,
  tone = "brand",
  defaultChecked = false,
}: {
  disabled: boolean;
  label: string;
  tone?: SwitchProps["tone"];
  defaultChecked?: boolean;
}) {
  return <Switch disabled={disabled} tone={tone} defaultChecked={defaultChecked} label={label} />;
}

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [disabled, setDisabled] = useState(true);
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <VStack className="switch-preview" gap="x8">
        <VStack gap="spacingY.componentDefault">
          <SwitchItem disabled={disabled} label="Not Checked (Brand)" />
          <SwitchItem disabled={disabled} defaultChecked label="Checked (Brand)" />
          <SwitchItem disabled={disabled} tone="neutral" label="Not Checked (Neutral)" />
          <SwitchItem disabled={disabled} tone="neutral" defaultChecked label="Checked (Neutral)" />
        </VStack>
        <Switch
          size="16"
          tone="neutral"
          checked={disabled}
          onCheckedChange={setDisabled}
          label="Disable switches"
        />
      </VStack>
    </view>
  );
}
```

### Listening to Value Changes

`onCheckedChange`를 사용하여 스위치의 선택 상태 변경을 감지할 수 있습니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Switch } from "@/components/ui/switch";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [count, setCount] = useState(0);
  const [lastValue, setLastValue] = useState<boolean | null>(null);
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <VStack className="switch-preview" gap="x4">
        <Switch
          label="Click me"
          onCheckedChange={(checked) => {
            setCount((previous) => previous + 1);
            setLastValue(checked);
          }}
        />
        <text className="switch-preview__status">
          onCheckedChange called: {count} times, last value:{" "}
          {lastValue === null ? "-" : JSON.stringify(lastValue)}
        </text>
      </VStack>
    </view>
  );
}
```

### Use Cases

#### Using `Switchmark`

`Switchmark`는 레이블을 제외한 스위치 컴포넌트로, 커스텀 레이아웃을 위해 사용할 수 있습니다.

```tsx
import "./styles";

import { HStack, Text, VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Switchmark } from "@/components/ui/switch";

interface CustomSwitchProps {
  label: string;
  textStyle: "t7Regular" | "t7Medium" | "t7Bold";
  defaultChecked?: boolean;
}

function CustomSwitch({ label, textStyle, defaultChecked = false }: CustomSwitchProps) {
  return (
    <VStack gap="x2" align="center">
      <Switchmark accessibility-label={label} defaultChecked={defaultChecked} />
      <Text textStyle={textStyle}>{label}</Text>
    </VStack>
  );
}

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  return (
    <view className={`${seedClassName} docs-lynx-switch-root`}>
      <HStack className="switch-preview" gap="x6">
        <CustomSwitch label="regular" textStyle="t7Regular" />
        <CustomSwitch label="medium" textStyle="t7Medium" defaultChecked />
        <CustomSwitch label="bold" textStyle="t7Bold" />
      </HStack>
    </view>
  );
}
```

## 웹 버전과의 차이

<Callout type="warning">
  Lynx `Switch`는 React `Switch`와 다음과 같은 차이가 있습니다.

  - **이벤트 핸들링**: `onChange` 대신 `onCheckedChange`만 노출합니다. tap 핸들러는 Switch 내부에서 소유합니다.
  - **렌더링 요소**: HTML `<label>` / `<input>` 대신 네이티브 `<view>` / `<text>` 요소를 렌더링합니다.
  - **Compound 구조**: `Switch.Root` → `Switch.Control` → `Switch.Thumb` / `Switch.Label` 구성과 Context로 상태/variant를 공유하는 흐름은 동일합니다. Control에 `tone`/`size`를 직접 전달해 Root를 override 하는 것도 지원합니다.
  - **접근성**: `Switch.Root`는 기본적으로 접근성 요소로 노출합니다. 역할 설명은 `switch`, 값은 선택 상태에 따라 `checked` 또는 `not checked`입니다. 비활성 상태에는 `disabled` trait을 전달합니다. Registry `Switch`는 문자열 `label`을 접근성 이름으로 사용합니다. `Switchmark`나 복합 레이블에는 `accessibility-label`을 직접 지정하세요.
  - **ref forwarding**: 모든 서브 컴포넌트는 `React.forwardRef`를 지원합니다.
</Callout>

## Scale Feedback

Lynx `Switch`는 현재 눌렀을 때 `Switchmark`가 줄어드는 피드백을 제공하지 않습니다. CSS 지원 문제가 아니라 현재 Rootage 명세와 Lynx Recipe에 pressed scale 상태가 없기 때문입니다. 이 피드백이 필요하면 앱에서 `Switchmark`를 감싸는 요소의 눌림 상태와 scale transform을 직접 연결하세요.

## Lynx 미지원 기능

현재 Lynx 플랫폼 제약으로 다음 기능이 지원되지 않습니다.

### 런타임 모델 차이로 제외

| 기능                                        | 웹 대응                      | 설명                           |
| ----------------------------------------- | ------------------------- | ---------------------------- |
| `SwitchHiddenInput`                       | `<input type="checkbox">` | Lynx에 HTML form 제출 모델 없음     |
| `name` / `value` / `required` / `invalid` | form field props          | Lynx에 native form 제출 모델 없음   |
| `focus` / `focusVisible`                  | 키보드 포커스                   | Lynx에 키보드 포커스 개념 없음          |
| `onChange` (raw DOM event)                | `React.ChangeEvent`       | 의미 없음. `onCheckedChange`로 대체 |