# Chip Tabs
URL: /lynx/components/chip-tabs
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/chip-tabs.mdx

Chip 형태로 표현된 탭 컴포넌트입니다. 카테고리나 필터를 선택하여 콘텐츠를 전환할 때 사용합니다.

Lynx Engine 최소 버전: 3.9
사용 XElement: <viewpager>, <viewpager-item>

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

## Preview

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralSolid"
        size="medium"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

## Installation

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

## Props

### `ChipTabsRoot`

### `ChipTabsList`

### `ChipTabsTrigger`

### `ChipTabsCarousel`

### `ChipTabsContent`

## Usage

```tsx
import { useState } from "@lynx-js/react";
import {
  ChipTabsList,
  ChipTabsRoot,
  ChipTabsTrigger,
} from "@/components/ui/chip-tabs";

export function App() {
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <>
      <ChipTabsRoot value={value} onValueChange={handleValueChange}>
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text>content 1</text>}
      {value === "2" && <text>content 2</text>}
      {value === "3" && <text>content 3</text>}
    </>
  );
}
```

`ChipTabsRoot`는 `value`와 `onValueChange`로 제어하거나 `defaultValue`로 초기 선택 값을 지정합니다. `ChipTabsTrigger`의 `notification` boolean은 label 옆 6px 간격에 작은 `NotificationBadge`를 표시합니다.

`ChipTabsCarousel`은 Registry에서 `ChipTabsCarouselCamera`를 조립하므로 `ChipTabsContent`만 자식으로 전달합니다. Carousel은 native `<viewpager>`이므로 Carousel 또는 Camera에 앱 레이아웃에 맞는 높이를 명시하고, `swipeable`로 좌우 스와이프를 켭니다. iOS의 화면 왼쪽 가장자리 뒤로가기 제스처를 우선할 범위는 `iosBackGestureEdgeWidth`로 정합니다.

공개 package API에서 Camera의 native `bindchange`, `bindwillchange`, `bindoffsetchange`를 직접 사용해야 할 때는 `ChipTabs.CarouselCamera`를 조합합니다. `onSwipeStart`, `onSwipeEnd`, `onSettle`은 Carousel에 전달해 스와이프 시작·종료·정착을 처리할 수 있습니다.

```tsx
import { useState } from "@lynx-js/react";
import { ChipTabs } from "@seed-design/lynx-react";

export function App() {
  const [lastEvent, setLastEvent] = useState("대기");

  function handleSwipeStart() {
    "background only";
    setLastEvent("스와이프 시작");
  }

  function handleSwipeEnd() {
    "background only";
    setLastEvent("스와이프 종료");
  }

  function handleSettle() {
    "background only";
    setLastEvent("정착");
  }

  return (
    <ChipTabs.Root defaultValue="1">
      <ChipTabs.List>
        <ChipTabs.Trigger value="1">라벨1</ChipTabs.Trigger>
        <ChipTabs.Trigger value="2">라벨2</ChipTabs.Trigger>
      </ChipTabs.List>
      <ChipTabs.Carousel
        style={{ height: "240px" }}
        swipeable
        iosBackGestureEdgeWidth={32}
        onSwipeStart={handleSwipeStart}
        onSwipeEnd={handleSwipeEnd}
        onSettle={handleSettle}
      >
        <ChipTabs.CarouselCamera>
          <ChipTabs.Content value="1"><text>content 1</text></ChipTabs.Content>
          <ChipTabs.Content value="2"><text>content 2</text></ChipTabs.Content>
        </ChipTabs.CarouselCamera>
      </ChipTabs.Carousel>
      <text>{lastEvent}</text>
    </ChipTabs.Root>
  );
}
```

## Scroll Alignment

`ChipTabsList`의 `scrollAlign`은 선택한 chip을 가로 목록에 맞추는 방식입니다. `"nearest"`, `"start"`, `"center"`, `"end"`를 사용할 수 있으며 기본값은 `"nearest"`입니다.

- `"start"`, `"center"`, `"end"`는 선택한 chip을 각각 목록의 시작, 가운데, 끝에 맞춥니다.
- `"nearest"`는 React Web의 최소 스크롤 동작과 같이 선택한 chip이 완전히 보이면 현재 위치를 유지합니다. 왼쪽이 잘렸을 때는 시작 경계까지, 오른쪽이 잘렸을 때는 끝 경계까지 필요한 만큼만 이동하므로 `"end"`처럼 항상 끝에 맞추지 않습니다.

실제 chip의 너비와 위치, viewport를 기준으로 계산하며, 가변 너비 chip도 그대로 유지합니다. 목록의 첫·마지막 항목을 가운데에 맞추기 위해 빈 공간을 추가하지 않고 스크롤 가능한 범위 안에서만 이동하며 항목 순서도 바꾸지 않습니다.

아래 예제에서 모드를 고르면 선택을 `라벨1`로 초기화합니다. 그 뒤 `라벨6`을 탭하거나 `6번 선택`을 탭해 controlled `value` 변경에서도 실제 scrollAlign 차이를 확인하세요. `nearest`를 고르면 `scrollAlign` prop을 생략하여 기본 동작도 함께 확인합니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { ActionButton, Box, HStack, Text, useSeedClassName, VStack } from "@seed-design/lynx-react";
import {
  ChipTabsList,
  ChipTabsRoot,
  ChipTabsTrigger,
  type ChipTabsListProps,
} from "@/components/ui/chip-tabs";

type ScrollAlign = NonNullable<ChipTabsListProps["scrollAlign"]>;

const ALIGNMENTS: ScrollAlign[] = ["nearest", "start", "center", "end"];
const LABELS = Array.from({ length: 15 }, (_, index) => String(index + 1));

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");
  const [scrollAlign, setScrollAlign] = useState<ScrollAlign>("nearest");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  function selectScrollAlign(nextScrollAlign: ScrollAlign) {
    "background only";
    setScrollAlign(nextScrollAlign);
    setValue("1");
  }

  function selectSixthChip() {
    "background only";
    setValue("6");
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root chip-tabs-scroll-alignment`}>
      <VStack gap="x3">
        <HStack className="chip-tabs-scroll-alignment__controls" wrap="wrap" gap="x2" p="x4">
          {ALIGNMENTS.map((nextScrollAlign) => (
            <ActionButton
              key={nextScrollAlign}
              className={`chip-tabs-scroll-alignment__mode-button chip-tabs-scroll-alignment__mode-button--${nextScrollAlign}`}
              variant={scrollAlign === nextScrollAlign ? "neutralSolid" : "neutralOutline"}
              bindtap={() => {
                "background only";
                selectScrollAlign(nextScrollAlign);
              }}
            >
              {nextScrollAlign}
            </ActionButton>
          ))}
          <ActionButton
            className="chip-tabs-scroll-alignment__select-sixth-button"
            variant="neutralOutline"
            bindtap={selectSixthChip}
          >
            6번 선택
          </ActionButton>
        </HStack>

        <Box px="x4">
          <Text className="chip-tabs-scroll-alignment__selected-value" textStyle="t5Regular">
            {`선택: 라벨${value}`}
          </Text>
        </Box>

        <Box className="chip-tabs-scroll-alignment__list-frame" width="360px" maxWidth="100%">
          <ChipTabsRoot value={value} onValueChange={handleValueChange}>
            <ChipTabsList scrollAlign={scrollAlign === "nearest" ? undefined : scrollAlign}>
              {LABELS.map((label) => (
                <ChipTabsTrigger key={label} value={label}>
                  {`라벨${label}`}
                </ChipTabsTrigger>
              ))}
            </ChipTabsList>
          </ChipTabsRoot>
        </Box>
      </VStack>
    </view>
  );
}
```

`nearest`에서 선택한 chip이 이미 완전히 보인 상태로 다시 선택하면 이동하지 않습니다. 목록을 직접 스크롤한 뒤에도 다음 선택이 필요한 경우에만 이동합니다.

## Examples

### Size=Medium

`medium`의 최소 높이는 36px입니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralSolid"
        size="medium"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

### Size=Large

`large`의 최소 높이는 40px입니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralSolid"
        size="large"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

### Variant=Neutral Solid

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralSolid"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

### Variant=Neutral Outline

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralOutline"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

### Notification

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [value, setValue] = useState("1");

  function handleValueChange(nextValue: string) {
    "background only";
    setValue(nextValue);
  }

  return (
    <view className={`${seedClassName} docs-lynx-chip-tabs-root`}>
      <ChipTabsRoot
        variant="neutralOutline"
        size="medium"
        defaultValue="1"
        value={value}
        onValueChange={handleValueChange}
      >
        <ChipTabsList>
          <ChipTabsTrigger notification value="1">
            라벨1
          </ChipTabsTrigger>
          <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
          <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
        </ChipTabsList>
      </ChipTabsRoot>
      {value === "1" && <text className="chip-tabs-preview__content-text">content 1</text>}
      {value === "2" && <text className="chip-tabs-preview__content-text">content 2</text>}
      {value === "3" && <text className="chip-tabs-preview__content-text">content 3</text>}
    </view>
  );
}
```

### With Scroll Fog

`ScrollFog`는 Registry snippet이나 Recipe 없이 `@seed-design/lynx-react` 패키지에서 직접 제공되는 package-only 공개 컴포넌트입니다. `ChipTabsList`를 `placement={["left", "right"]}`인 `ScrollFog`로 감싸면 기본 20px fog가 좌우 edge에 표시됩니다. List의 내부 좌우 padding 16px은 그대로 유지합니다.

```tsx
import "./styles";

import { ScrollFog, useSeedClassName } from "@seed-design/lynx-react";
import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "@/components/ui/chip-tabs";

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

  return (
    <view className={seedClassName} style={{ maxWidth: "360px" }}>
      <ChipTabsRoot defaultValue="1">
        <ScrollFog style={{ width: "100%", height: "36px" }} placement={["left", "right"]}>
          <ChipTabsList>
            <ChipTabsTrigger value="1">라벨1</ChipTabsTrigger>
            <ChipTabsTrigger value="2">라벨2</ChipTabsTrigger>
            <ChipTabsTrigger value="3">라벨3</ChipTabsTrigger>
            <ChipTabsTrigger value="4">라벨4</ChipTabsTrigger>
            <ChipTabsTrigger value="5">라벨5</ChipTabsTrigger>
            <ChipTabsTrigger value="6">라벨6</ChipTabsTrigger>
            <ChipTabsTrigger value="7">라벨7</ChipTabsTrigger>
            <ChipTabsTrigger value="8">라벨8</ChipTabsTrigger>
            <ChipTabsTrigger value="9">라벨9</ChipTabsTrigger>
            <ChipTabsTrigger value="10">라벨10</ChipTabsTrigger>
            <ChipTabsTrigger value="11">라벨11</ChipTabsTrigger>
            <ChipTabsTrigger value="12">라벨12</ChipTabsTrigger>
            <ChipTabsTrigger value="13">라벨13</ChipTabsTrigger>
            <ChipTabsTrigger value="14">라벨14</ChipTabsTrigger>
            <ChipTabsTrigger value="15">라벨15</ChipTabsTrigger>
          </ChipTabsList>
        </ScrollFog>
      </ChipTabsRoot>
    </view>
  );
}
```

## Web Version Differences

| 항목       | React Web                 | Lynx                                             |
| -------- | ------------------------- | ------------------------------------------------ |
| 렌더링 요소   | HTML `div`, `button`      | 네이티브 `view`, `text`, `scroll-view`, `viewpager`  |
| 탭 선택 이벤트 | `onClick` 기반              | `bindtap` 기반, 공개 상태 이벤트는 `onValueChange`         |
| 콘텐츠      | Root 바깥의 조건부 `div`도 사용 가능 | Root 바깥에서 value에 따른 조건부 native `text`를 렌더링할 수 있음 |
| 가로 List  | CSS overflow              | 네이티브 가로 `scroll-view`                            |
| Carousel | 웹 Carousel                | 네이티브 `<viewpager>`                               |

React 예제와 마찬가지로 Lynx에서도 Root 바깥에서 선택 값에 따라 조건부 native `text` 콘텐츠를 렌더링할 수 있습니다. 별도 AppBar, 화면 shell, CTA, asset은 제공하지 않습니다.

## Unsupported Lynx Features

- 키보드 포커스와 roving focus
- RTL 순서와 스와이프 방향 반전
- `lazyMount`, `unmountOnExit`: native viewpager는 모든 page slot을 유지합니다.
- Carousel의 `loop`, `autoHeight`, `dragThreshold`, `carouselPreventDrag`
- 콘텐츠 전환 애니메이션