Tag Group

텍스트 태그를 수평으로 나열해 여러 속성·상태·메타데이터를 한눈에 보여주는 정보 요약 컴포넌트입니다.

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

Lynx 예제를 불러오는 중입니다.

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

npx @seed-design/cli add ui:tag-group

pnpm dlx @seed-design/cli add ui:tag-group

yarn dlx @seed-design/cli add ui:tag-group

bun x @seed-design/cli add ui:tag-group

의존성 설치

npm install @seed-design/lynx-react

yarn add @seed-design/lynx-react

pnpm add @seed-design/lynx-react

bun add @seed-design/lynx-react

아래 코드를 복사 후 붙여넣고 사용하세요

/**
 * @file ui:tag-group
 * @requires @seed-design/lynx-react@>=0.1.0 <1.0.0
 * @requires @seed-design/lynx-css@>=0.1.0 <1.0.0
 **/

/**
 * @see https://seed-design.io/lynx/components/tag-group
 */
import * as React from "@lynx-js/react";
import { TagGroup as SeedTagGroup } from "@seed-design/lynx-react";

export interface TagGroupRootProps extends SeedTagGroup.RootProps {}

export const TagGroupRoot = SeedTagGroup.Root;

export interface TagGroupItemProps extends Omit<SeedTagGroup.ItemProps, "children"> {
  label: React.ReactNode;
}

export const TagGroupItem = React.forwardRef<unknown, TagGroupItemProps>(
  ({ label, ...props }, ref) => {
    return (
      <SeedTagGroup.Item {...props} ref={ref}>
        <SeedTagGroup.ItemLabel>{label}</SeedTagGroup.ItemLabel>
      </SeedTagGroup.Item>
    );
  },
);
TagGroupItem.displayName = "TagGroupItem";

/**
 * This file is a snippet from SEED Design, helping you get started quickly with @seed-design/* packages.
 * You can extend this snippet however you want.
 */

Examples

Usage

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

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

Lynx 예제를 불러오는 중입니다.

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

Lynx 예제를 불러오는 중입니다.

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

Lynx 예제를 불러오는 중입니다.

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 설정은 같게 유지합니다.

Lynx 예제를 불러오는 중입니다.

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에서 빈 문자열이 됩니다. 이 예제에서는 두 번째 구분 기호로 /를 사용합니다.

Lynx 예제를 불러오는 중입니다.

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도 지원하지 않습니다. 아이콘이나 한 줄 말줄임이 필요하면 앱에서 별도 레이아웃으로 구성하세요.

Lynx 예제를 불러오는 중입니다.

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>
  );
}

웹 버전과의 차이

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

렌더링 요소

슬롯	웹	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>의 별칭입니다.

Tag Group

Installation

의존성 설치

아래 코드를 복사 후 붙여넣고 사용하세요

Props

`TagGroupRoot`

`TagGroupItem`

Examples

Usage

Sizes

Weights

Tones

With Icons

Customizing `TagGroupItem`

Customizing Separators

Wrapping Behavior

웹 버전과의 차이

렌더링 요소

레이아웃 모델 차이

구분자 공백 처리

미지원 prop

이벤트·ref

목차

Tag Group

Manual Installation

의존성 설치

아래 코드를 복사 후 붙여넣고 사용하세요

목차