> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/tag.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Tag

Label content categories or statuses.


## Basic usage

Use Tag to add a short category or status label to content.


In progress

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/basic.tsx"
import { Tag } from '@ifhover/leaf-ui';

export function TagBasic() {
  return <Tag>In progress</Tag>;
}
```

Expand code


## Examples

### Colors

The default tag uses a gray background and black text. This example shows every built-in color and a custom color.


DefaultSuccessInfoWarningDangerCustom

colors.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/colors.tsx"
import { Flex, Tag } from '@ifhover/leaf-ui';

export function TagColors() {
  return (
    <Flex gap="sm" wrap>
      <Tag>Default</Tag>
      <Tag color="success">Success</Tag>
      <Tag color="info">Info</Tag>
      <Tag color="warning">Warning</Tag>
      <Tag color="danger">Danger</Tag>
      <Tag color="#722ed1">Custom</Tag>
    </Flex>
  );
}
```

Expand code

### Appearance

Use `variant` `soft` for a light background with colored text or `solid` for a colored background with white text. The example shows every built-in color and a custom color.


softDefaultSuccessInfoWarningDangerCustom

solidDefaultSuccessInfoWarningDangerCustom

variants.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/variants.tsx"
import { Flex, Tag, Text } from '@ifhover/leaf-ui';

export function TagVariants() {
  return (
    <Flex direction="column" gap="sm" align="start">
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">soft</Text>
        <Tag>Default</Tag>
        <Tag color="success">Success</Tag>
        <Tag color="info">Info</Tag>
        <Tag color="warning">Warning</Tag>
        <Tag color="danger">Danger</Tag>
        <Tag color="#722ed1">Custom</Tag>
      </Flex>
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">solid</Text>
        <Tag variant="solid">Default</Tag>
        <Tag color="success" variant="solid">
          Success
        </Tag>
        <Tag color="info" variant="solid">
          Info
        </Tag>
        <Tag color="warning" variant="solid">
          Warning
        </Tag>
        <Tag color="danger" variant="solid">
          Danger
        </Tag>
        <Tag color="#722ed1" variant="solid">
          Custom
        </Tag>
      </Flex>
    </Flex>
  );
}
```

Expand code

### Icons

This example shows `soft` and `solid` appearances with every built-in color and a custom color. Tags no longer provide a built-in dot.


softDefaultSuccessInfoWarningDangerCustom

solidDefaultSuccessInfoWarningDangerCustom

icons.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/icons.tsx"
import { Flex, Tag, Text } from '@ifhover/leaf-ui';
import { Check, CircleAlert, CircleX, Info, Sparkles, Tag as TagIcon } from 'lucide-react';

export function TagIcons() {
  return (
    <Flex direction="column" gap="sm" align="start">
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">soft</Text>
        <Tag icon={<TagIcon />}>Default</Tag>
        <Tag color="success" icon={<Check />}>
          Success
        </Tag>
        <Tag color="info" icon={<Info />}>
          Info
        </Tag>
        <Tag color="warning" icon={<CircleAlert />}>
          Warning
        </Tag>
        <Tag color="danger" icon={<CircleX />}>
          Danger
        </Tag>
        <Tag color="#722ed1" icon={<Sparkles />}>
          Custom
        </Tag>
      </Flex>
      <Flex gap="sm" align="center" wrap>
        <Text tone="muted">solid</Text>
        <Tag variant="solid" icon={<TagIcon />}>
          Default
        </Tag>
        <Tag color="success" variant="solid" icon={<Check />}>
          Success
        </Tag>
        <Tag color="info" variant="solid" icon={<Info />}>
          Info
        </Tag>
        <Tag color="warning" variant="solid" icon={<CircleAlert />}>
          Warning
        </Tag>
        <Tag color="danger" variant="solid" icon={<CircleX />}>
          Danger
        </Tag>
        <Tag color="#722ed1" variant="solid" icon={<Sparkles />}>
          Custom
        </Tag>
      </Flex>
    </Flex>
  );
}
```

Expand code

### Sizes

Set the size with `size`; the default is `md`.


Small

In progress

Medium

In progress

Large

In progress

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/sizes.tsx"
import { Flex, Grid, Tag, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
] as const;

export function TagSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Tag size={value}>In progress</Tag>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

Expand code

[](#)
### Checkable tag

Use `CheckableTag` for a toggle selection and control it with `checked` and `onChange`.


Favorites only

checkable.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/checkable.tsx"
import { CheckableTag } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TagCheckable() {
  const [checked, setChecked] = useState(false);
  return (
    <CheckableTag checked={checked} onChange={setChecked}>
      Favorites only
    </CheckableTag>
  );
}
```

Expand code

### Tag selection

Use `TagGroup` for multiple options. `value` and `onChange` use an array of strings.


DesignDevelopment

Selected: design

selection.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/selection.tsx"
import { Space, TagGroup, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TagSelection() {
  const [value, setValue] = useState<string[]>(['design']);
  return (
    <Space direction="vertical" align="stretch">
      <TagGroup
        options={[
          { value: 'design', label: 'Design' },
          { value: 'dev', label: 'Development' },
        ]}
        value={value}
        onChange={setValue}
      />
      <Text tone="muted" role="status">
        Selected: {value.join(', ') || 'None'}
      </Text>
    </Space>
  );
}
```

Expand code

With `name`, a native form submits the selection as a JSON array string, or an empty string when nothing is selected. Reset application state as well when resetting a controlled tag group.

### Closable tags

Set `closable` to allow removal. Update a dynamic list with `onClose`, or call `event.preventDefault()` to prevent the default removal.


LeafReact

closable.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/tag/closable.tsx"
import { Space, Tag, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TagClosable() {
  const [tags, setTags] = useState(['Leaf', 'React']);
  return (
    <Space wrap>
      {tags.map((tag) => (
        <Tag
          key={tag}
          closable
          onClose={() => setTags((items) => items.filter((item) => item !== tag))}
        >
          {tag}
        </Tag>
      ))}
      {tags.length === 0 && (
        <Text tone="muted" role="status">
          All tags closed
        </Text>
      )}
    </Space>
  );
}
```

Expand code


## API

### Tag API

Configure tag content, appearance and closing.

| Property   | Type                                                                         | Default     | Description                                                                                       |
| ---------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `children` | `ReactNode`                                                                  | —           | Child content.                                                                                    |
| `color`    | `'default' \| 'success' \| 'warning' \| 'danger' \| 'info' \| (string & {})` | `'default'` | Gray by default; use one of four semantic presets or a custom color                               |
| `variant`  | `'soft' \| 'solid'`                                                          | `'soft'`    | `soft` uses a light background and colored text; `solid` uses a colored background and white text |
| `size`     | `'sm' \| 'md' \| 'lg'`                                                       | `'md'`      | Tag size                                                                                          |
| `icon`     | `ReactNode`                                                                  | —           | Show a custom icon                                                                                |
| `closable` | `boolean`                                                                    | `false`     | Show a close button                                                                               |
| `onClose`  | `(event: MouseEvent<HTMLButtonElement>) => void`                             | —           | Called on close                                                                                   |

### CheckableTagProps API

Configure selection state and change events for a checkable tag.

| Property         | Type                         | Default | Description              |
| ---------------- | ---------------------------- | ------- | ------------------------ |
| `checked`        | `boolean`                    | —       | Controlled checked state |
| `defaultChecked` | `boolean`                    | `false` | Initial checked state    |
| `onChange`       | `(checked: boolean) => void` | —       | Value change callback    |
| `size`           | `'sm' \| 'md' \| 'lg'`       | `'md'`  | Tag size.                |

### TagGroupProps API

Manage selected values and presentation for a group of tag options.

| Property       | Type                                         | Default  | Description                                                 |
| -------------- | -------------------------------------------- | -------- | ----------------------------------------------------------- |
| `options`      | `readonly `[`TagOption`](#tagoption-api)`[]` | Required | Available options                                           |
| `value`        | `readonly string[]`                          | —        | Controlled value                                            |
| `defaultValue` | `readonly string[]`                          | `[]`     | Initial value, restored by uncontrolled form resets         |
| `onChange`     | `(values: string[]) => void`                 | —        | Value change callback                                       |
| `disabled`     | `boolean`                                    | —        | Disable interaction.                                        |
| `size`         | `'sm' \| 'md' \| 'lg'`                       | `'md'`   | Tag size.                                                   |
| `name`         | `string`                                     | —        | Form field name                                             |
| `form`         | `string`                                     | —        | Associated form ID                                          |
| `required`     | `boolean`                                    | —        | Require a non-empty value; compound controls validate once. |

### TagOption API

An individual option supplied to a tag group.

| Property   | Type        | Default  | Description          |
| ---------- | ----------- | -------- | -------------------- |
| `value`    | `string`    | Required | Controlled value     |
| `label`    | `ReactNode` | Required | Display label        |
| `disabled` | `boolean`   | —        | Disable interaction. |
