# Segmented Control
URL: /lynx/components/segmented-control
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/segmented-control.mdx

여러 옵션 중 하나를 선택하여 관련 콘텐츠를 즉시 필터링하거나 전환할 때 사용하는 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6

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

## Preview

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl
          className="segmented-control-example__control"
          defaultValue="Hot"
          accessibility-label="Sort by"
        >
          <SegmentedControlItem value="Hot">Hot</SegmentedControlItem>
          <SegmentedControlItem value="New">New</SegmentedControlItem>
        </SegmentedControl>
      </view>
    </view>
  );
}
```

## Installation

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

## Props

### `SegmentedControl`

<Callout type="info">
  `value`와 `defaultValue` 중 적어도 하나를 제공해야 선택된 항목과 Indicator를 표시할 수 있습니다.
</Callout>

### `SegmentedControlItem`

## Usage

```tsx
import {
  SegmentedControl,
  SegmentedControlItem,
} from "@/components/ui/segmented-control";

export function App() {
  return (
    <SegmentedControl defaultValue="hot" accessibility-label="정렬 기준">
      <SegmentedControlItem value="hot">인기순</SegmentedControlItem>
      <SegmentedControlItem value="new">최신순</SegmentedControlItem>
    </SegmentedControl>
  );
}
```

Registry의 `SegmentedControl`은 선택 Indicator를 자동으로 추가합니다.

## Examples

### Disabled

`SegmentedControl`의 `disabled`는 전체 항목을 비활성화합니다. 각 `SegmentedControlItem`도 따로 비활성화할 수 있습니다.

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl defaultValue="Hot" disabled accessibility-label="Sort by">
          <SegmentedControlItem value="Hot">Hot</SegmentedControlItem>
          <SegmentedControlItem value="New">New</SegmentedControlItem>
        </SegmentedControl>
        <SegmentedControl defaultValue="Marinara" accessibility-label="Pasta">
          <SegmentedControlItem value="Marinara">Marinara</SegmentedControlItem>
          <SegmentedControlItem value="Alfredo" disabled>
            Alfredo
          </SegmentedControlItem>
          <SegmentedControlItem value="Pesto" disabled>
            Pesto
          </SegmentedControlItem>
          <SegmentedControlItem value="Carbonara">Carbonara</SegmentedControlItem>
          <SegmentedControlItem value="Bolognese">Bolognese</SegmentedControlItem>
        </SegmentedControl>
      </view>
    </view>
  );
}
```

### Notification

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { ActionButton, useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [sortBy, setSortBy] = useState("monthly");
  const [hasSeenAnnual, setHasSeenAnnual] = useState(false);

  function handleValueChange(value: string) {
    "background only";
    setSortBy(value);

    if (value === "annual") setHasSeenAnnual(true);
  }

  function handleResetNotification() {
    "background only";
    setHasSeenAnnual(false);
  }

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl
          accessibility-label="Billing Method"
          value={sortBy}
          onValueChange={handleValueChange}
        >
          <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
          <SegmentedControlItem value="annual" notification={!hasSeenAnnual}>
            Annual
          </SegmentedControlItem>
          <SegmentedControlItem value="enterprise">Enterprise Custom</SegmentedControlItem>
        </SegmentedControl>
        <ActionButton
          size="xsmall"
          variant="neutralSolid"
          disabled={!hasSeenAnnual}
          bindtap={handleResetNotification}
        >
          Reset Notification
        </ActionButton>
      </view>
    </view>
  );
}
```

### Long Label

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl defaultValue="price" accessibility-label="정렬 기준">
          <SegmentedControlItem value="price">가격 높은 순</SegmentedControlItem>
          <SegmentedControlItem value="discount">할인율 높은 순</SegmentedControlItem>
          <SegmentedControlItem value="popular">인기 많은 순</SegmentedControlItem>
        </SegmentedControl>
      </view>
    </view>
  );
}
```

### Fixed Width

`SegmentedControl`의 `style`이나 `className`으로 너비를 지정할 수 있습니다.

```tsx
import "./styles";

import { useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl
          className="segmented-control-example__fixed-wide"
          defaultValue="new"
          accessibility-label="Sort by"
        >
          <SegmentedControlItem value="new">New</SegmentedControlItem>
          <SegmentedControlItem value="hot">Hot</SegmentedControlItem>
        </SegmentedControl>
        <SegmentedControl
          className="segmented-control-example__fixed-narrow"
          defaultValue="oneway"
          accessibility-label="Trip Type"
        >
          <SegmentedControlItem value="oneway">One Way Trip</SegmentedControlItem>
          <SegmentedControlItem notification value="round">
            Round Trip
          </SegmentedControlItem>
          <SegmentedControlItem notification value="multi">
            Multi-City Journey
          </SegmentedControlItem>
        </SegmentedControl>
      </view>
    </view>
  );
}
```

### Listening to Value Changes

`onValueChange`로 선택 값 변경을 감지할 수 있습니다. Controlled 모드에서는 `value`와 함께 사용합니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [count, setCount] = useState(0);
  const [lastValue, setLastValue] = useState<string | null>(null);

  function handleValueChange(nextValue: string) {
    "background only";
    setCount((previous) => previous + 1);
    setLastValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-segmented-control-root`}>
      <view className="segmented-control-example">
        <SegmentedControl
          defaultValue="hot"
          onValueChange={handleValueChange}
          accessibility-label="Sort by"
        >
          <SegmentedControlItem value="hot">Hot</SegmentedControlItem>
          <SegmentedControlItem value="new">New</SegmentedControlItem>
        </SegmentedControl>
        <text className="segmented-control-example__status">
          onValueChange called: {count} times, last value: {lastValue ?? "-"}
        </text>
      </view>
    </view>
  );
}
```

## 웹 버전과의 차이

| 항목        | React Web                  | Lynx                                  |
| --------- | -------------------------- | ------------------------------------- |
| 렌더링 요소    | HTML `label`, `input`      | 네이티브 `view`, `text`                   |
| 선택 이벤트    | input change               | `bindtap`, 공개 상태 이벤트는 `onValueChange` |
| 접근성       | ARIA `radiogroup`, `radio` | Lynx `accessibility-*` 속성             |
| Indicator | CSS grid와 custom property  | Grid layout과 custom property          |

## Lynx 미지원 기능

- HTML form 제출을 위한 `ItemHiddenInput`, `name`, `form`, `inputProps`
- 키보드 focus와 focus-visible 상호작용
- `SegmentedControlItem`의 `invalid` 상태

Lynx Registry와 package는 `invalid` 상태를 제공하지 않습니다. 이 차이는 의도된 미지원입니다. 오류 상태가 필요하면 앱에서 `SegmentedControl` 가까이에 오류 문구를 표시하고, `accessibility-label`에도 오류 내용을 포함하세요.