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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/tag.md.

Tag

Label content categories or statuses.

Basic usage

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

In progress
basic.tsx
import { Tag } from '@ifhover/leaf-ui';

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

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

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

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

Sizes

Set the size with size; the default is md.

Small
In progress
Medium
In progress
Large
In progress
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>
  );
}

Checkable tag

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

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

Tag selection

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

Selected: design
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>
  );
}

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

API

Tag API

Configure tag content, appearance and closing.

PropertyTypeDefaultDescription
childrenReactNode—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
iconReactNode—Show a custom icon
closablebooleanfalseShow a close button
onClose(event: MouseEvent<HTMLButtonElement>) => void—Called on close

CheckableTagProps API

Configure selection state and change events for a checkable tag.

PropertyTypeDefaultDescription
checkedboolean—Controlled checked state
defaultCheckedbooleanfalseInitial 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.

PropertyTypeDefaultDescription
optionsreadonly TagOption[]RequiredAvailable options
valuereadonly string[]—Controlled value
defaultValuereadonly string[][]Initial value, restored by uncontrolled form resets
onChange(values: string[]) => void—Value change callback
disabledboolean—Disable interaction.
size'sm' | 'md' | 'lg''md'Tag size.
namestring—Form field name
formstring—Associated form ID
requiredboolean—Require a non-empty value; compound controls validate once.

TagOption API

An individual option supplied to a tag group.

PropertyTypeDefaultDescription
valuestringRequiredControlled value
labelReactNodeRequiredDisplay label
disabledboolean—Disable interaction.