# Tag Group
URL: /lynx/components/tag-group
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/tag-group.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 { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <view className="tag-group-preview">
        <TagGroupRoot className="tag-group-preview__group">
          <TagGroupItem label="500m" />
          <TagGroupItem label="서초4동" />
          <TagGroupItem label="3분 전" />
        </TagGroupRoot>
      </view>
    </view>
  );
}
```

## Installation

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

## Props

### `TagGroupRoot`

### `TagGroupItem`

## Examples

### Usage

설치한 snippet은 `TagGroupRoot`와 `TagGroupItem`을 export 합니다. `TagGroupItem`은 `label` prop을 받아 내부에서 Lynx `<text>` label을 렌더합니다.

```tsx
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

export function App() {
  return (
    <TagGroupRoot size="t2">
      <TagGroupItem label="동네 인증" />
      <TagGroupItem label="매너 온도 42.0°C" />
      <TagGroupItem tone="brand" weight="bold" label="추천" />
    </TagGroupRoot>
  );
}
```

`TagGroupRoot`의 `size`·`weight`·`tone`은 Context로 하위 `TagGroupItem`에 전파되며, 개별 `TagGroupItem`에서 prop으로 덮어쓸 수 있습니다. 구분자는 기본 `"·"`이고 `separator` prop으로 바꿀 수 있습니다.

`TagGroupItem`은 `flexShrink`를 지원합니다. 긴 태그가 있는 레이아웃에서 item의 축소 우선순위를 조정해야 할 때 사용하세요.

`TagGroup`은 정보를 읽기 전용으로 나열하는 컴포넌트입니다. 단일·다중 선택, 선택 값 변경, 비활성화 상태를 위한 API는 제공하지 않습니다. 사용자가 값을 선택해야 한다면 단일 선택에는 `RadioGroup`, 다중 선택에는 `Checkbox`를 사용하세요.

### Sizes

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <VStack className="tag-group-preview" gap="spacingY.componentDefault">
        <TagGroupRoot size="t2" className="tag-group-preview__group">
          <TagGroupItem label="t2" />
          <TagGroupItem label="t2" />
          <TagGroupItem label="t2" />
        </TagGroupRoot>
        <TagGroupRoot size="t3" className="tag-group-preview__group">
          <TagGroupItem label="t3" />
          <TagGroupItem label="t3" />
          <TagGroupItem label="t3" />
        </TagGroupRoot>
        <TagGroupRoot size="t4" className="tag-group-preview__group">
          <TagGroupItem label="t4" />
          <TagGroupItem label="t4" />
          <TagGroupItem label="t4" />
        </TagGroupRoot>
      </VStack>
    </view>
  );
}
```

### Weights

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <VStack className="tag-group-preview" gap="spacingY.componentDefault">
        <TagGroupRoot weight="regular" className="tag-group-preview__group">
          <TagGroupItem label="regular" />
          <TagGroupItem label="regular" />
          <TagGroupItem label="regular" />
        </TagGroupRoot>
        <TagGroupRoot weight="bold" className="tag-group-preview__group">
          <TagGroupItem label="bold" />
          <TagGroupItem label="bold" />
          <TagGroupItem label="bold" />
        </TagGroupRoot>
      </VStack>
    </view>
  );
}
```

### Tones

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <VStack className="tag-group-preview" gap="spacingY.componentDefault">
        <TagGroupRoot tone="neutralSubtle" className="tag-group-preview__group">
          <TagGroupItem label="neutralSubtle" />
          <TagGroupItem label="neutralSubtle" />
          <TagGroupItem label="neutralSubtle" />
        </TagGroupRoot>
        <TagGroupRoot tone="neutral" className="tag-group-preview__group">
          <TagGroupItem label="neutral" />
          <TagGroupItem label="neutral" />
          <TagGroupItem label="neutral" />
        </TagGroupRoot>
        <TagGroupRoot tone="brand" className="tag-group-preview__group">
          <TagGroupItem label="brand" />
          <TagGroupItem label="brand" />
          <TagGroupItem label="brand" />
        </TagGroupRoot>
      </VStack>
    </view>
  );
}
```

### With Icons

Lynx Registry의 `TagGroupItem`은 `prefixIcon`과 `suffixIcon`을 제공하지 않습니다. 아이콘이 필요한 정보는 앱에서 별도 레이아웃으로 구성하세요.

### Customizing `TagGroupItem`

`TagGroupRoot`의 `tone`과 `weight`은 그룹 기본값으로 전달됩니다. 개별 `TagGroupItem`에서 필요한 값만 덮어쓸 수 있습니다.

내부 요소를 직접 구성해야 할 때만 `@seed-design/lynx-react`의 컴파운드 컴포넌트를 함께 사용하세요.

React 예제의 아이콘은 Lynx Registry에 대응하는 prop이 없어 생략합니다. 텍스트와 항목 수, 개별 tone과 weight 설정은 같게 유지합니다.

```tsx
import "./styles";

import { TagGroup as SeedTagGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <VStack className="tag-group-preview" gap="spacingY.componentDefault">
        <TagGroupRoot className="tag-group-preview__group">
          <SeedTagGroup.Item weight="bold" tone="neutral">
            <SeedTagGroup.ItemLabel>4.5</SeedTagGroup.ItemLabel>
          </SeedTagGroup.Item>
          <TagGroupItem label="후기 37" />
          <TagGroupItem label="단골 12" />
        </TagGroupRoot>
        <TagGroupRoot tone="neutral" className="tag-group-preview__group">
          <TagGroupItem tone="brand" label="인증됨" />
          <TagGroupItem label="10" />
          <TagGroupItem label="3" />
        </TagGroupRoot>
      </VStack>
    </view>
  );
}
```

### Customizing Separators

`TagGroupRoot`의 `separator`로 구분 기호를 바꿀 수 있습니다. 의미가 있는 정보는 구분자 대신 `TagGroupItem`으로 표현하세요.

문자열 구분자의 앞뒤 공백은 Lynx에서 제거됩니다. 예를 들어 `separator=" / "`와 `separator="/"`는 동일하게 렌더링되며, 항목과 구분자 사이의 간격은 컴포넌트가 일관되게 적용합니다.

따라서 웹 예제의 공백 한 칸 구분자는 Lynx에서 빈 문자열이 됩니다. 이 예제에서는 두 번째 구분 기호로 `/`를 사용합니다.

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <VStack className="tag-group-preview" gap="spacingY.componentDefault">
        <TagGroupRoot separator=" | " size="t4" className="tag-group-preview__group">
          <TagGroupItem label="가" />
          <TagGroupItem label="나" />
          <TagGroupItem label="다" />
          <TagGroupItem label="라" />
        </TagGroupRoot>
        <TagGroupRoot separator=" / " size="t4" className="tag-group-preview__group">
          <TagGroupItem label="가" />
          <TagGroupItem label="나" />
          <TagGroupItem label="다" />
          <TagGroupItem label="라" />
        </TagGroupRoot>
      </VStack>
    </view>
  );
}
```

### Wrapping Behavior

컨테이너 너비를 초과하면 구분자와 뒤따르는 item이 하나의 단위로 다음 줄에 배치됩니다.

기본 줄바꿈 예제는 React와 같은 문구와 컨테이너 너비를 사용하지만 아이콘은 생략합니다. Lynx에서는 `truncate`도 지원하지 않습니다. 아이콘이나 한 줄 말줄임이 필요하면 앱에서 별도 레이아웃으로 구성하세요.

```tsx
import "./styles";

import { Text, VStack, useSeedClassName } from "@seed-design/lynx-react";
import { TagGroupRoot, TagGroupItem } from "@/components/ui/tag-group";

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

  return (
    <view className={`${seedClassName} docs-lynx-tag-group-root`}>
      <view className="tag-group-preview">
        <VStack className="tag-group-preview__wrapping-container" gap="x1" align="flex-start">
          <Text textStyle="t2Medium">default (wrap)</Text>
          <TagGroupRoot className="tag-group-preview__wrapping-group">
            <TagGroupItem label="부산광역시 해운대구" />
            <TagGroupItem label="123 456 789 012 345" />
            <TagGroupItem label="Ut minim laboris enim" />
          </TagGroupRoot>
        </VStack>
      </view>
    </view>
  );
}
```

## 웹 버전과의 차이

<Callout type="warning">
  Lynx TagGroup은 Lynx view 엔진(Yoga 기반 flex)의 제약으로 React 웹 버전과 다음과 같은 차이가 있습니다.
</Callout>

### 렌더링 요소

| 슬롯         | 웹                 | Lynx                                       |
| ---------- | ----------------- | ------------------------------------------ |
| Root       | `<span>` (inline) | `<view>` (flex-row, flex-wrap, width 100%) |
| Separator  | `<span>`          | `<text>`                                   |
| Item       | `<span>` (inline) | `<view>` (flex-row, flex-shrink 0)         |
| Item Label | `<span>`          | `<text>`                                   |

### 레이아웃 모델 차이

- **웹**: `display: inline` 기반 text flow. 컨테이너가 좁으면 마지막 item 내부 label text가 word 단위로 자연스럽게 wrap됩니다 (예: `"Ut minim laboris enim"` → `"Ut minim"` / `"laboris enim"` 두 줄로 쪼개짐).
- **Lynx**: flex 기반 item 단위 wrap. item은 content-size를 유지하고, 한 줄에 들어가지 않으면 item 전체가 다음 줄로 이동합니다. item 내부 text가 item 경계를 넘어 word-break되는 동작은 재현할 수 없습니다. Lynx `TagGroupRoot`는 이를 자연스럽게 보이도록 separator를 뒤따르는 item과 하나의 wrap 단위로 묶어 다음 줄로 함께 이동시킵니다.

### 구분자 공백 처리

웹은 `white-space: pre`로 문자열 구분자의 앞뒤 공백을 보존합니다. Lynx는 `white-space: pre`를 지원하지 않고 브라우저 프리뷰와 네이티브 Lynx의 기본 공백 계측도 서로 다릅니다. 두 실행 환경에서 같은 간격을 만들기 위해 Lynx `TagGroup`은 문자열 구분자의 앞뒤 공백을 제거하고 컴포넌트 스타일의 간격을 적용합니다. 문자열이 아닌 `ReactNode` 구분자는 변경하지 않습니다.

### 미지원 prop

| prop                               | 웹 동작                        | Lynx 미지원 사유                                                                                                    |
| ---------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `truncate` (Root)                  | 한 줄 유지 + 모든 item label의 말줄임 | Lynx flex 모델에서는 label이 item 너비에 맞춰지지 않아 웹 수준의 inline ellipsis가 동작하지 않음. 모든 item에 말줄임을 일괄 적용하는 경험이 자연스럽지 않아 제거됨 |
| `asChild` (Root/Item)              | Slot 기반 다형 렌더               | Lynx에서 Primitive Slot 패턴 미제공                                                                                   |
| `prefixIcon` / `suffixIcon` (Item) | 아이콘 + 라벨                    | 현재 Lynx Registry와 Recipe에 아이콘 prop과 slot이 없음                                                                   |

### 이벤트·ref

- 이벤트: Lynx는 `onClick` 대신 `bindtap` / `main-thread:bindtap`을 사용합니다. `TagGroup`은 정적 표시 컴포넌트이므로 선택 값이나 비활성화 상태를 관리하는 인터랙션 prop은 노출하지 않습니다.
- ref: Root와 Item의 ref는 `<view>`로 전달됩니다. 내부에서는 `LynxViewRef`를 사용하며, 이 타입은 `React.Ref<NodesRef>`의 별칭입니다.