Documentation

Introduction Get Started Theming Tokens Roadmap Changelog llms.txt

Components

Charts

X AI

Kiosk

Tag

A short label for a category, a status or a keyword, optionally closable and optionally something the reader can pick.

Code

Tag is installed into your project as a file you own. It takes the same props as Ant Design v6's Tag and adds emphasis, size, shape, status with statusColor, and avatar.

It also changes three things without a prop: color takes palettes from your theme, like fuchsia or the gray slate, preset text is one shade darker to meet WCAG AA, and an icon with no children makes a square tag. Rows the kit adds are marked antuikit in the API table.

Install

npx antuikit@latest init

npx antuikit@latest add tag

The first command installs AntuikitProvider and the theme tokens, the second adds this component. Tag needs both: emphasis="subtle" uses the theme's classes, and status brings Badge with it.

Import

From @/components/ui/tag, never from antd. The file lives in your project, so the import is a path, not a package.

import { Tag } from "@/components/ui/tag"

The axes

The enumerated props and their values. They combine: a color, painted by a variant, quieted by an emphasis and sized by a size.

color takes the five status names, antd's presets (blue, green, gold and the rest), a palette from your theme (the default theme adds amber, emerald, teal, sky, indigo, violet, fuchsia, rose and grays like slate and zinc), or any CSS color. A Tag with no color is the neutral one.
variant takes filled, solid and outlined. Unset, it uses the variant set on ConfigProvider, then filled.
emphasis (antuikit) takes default and subtle. For a loud tag, use variant="solid".
size (antuikit) takes medium and small.
shape (antuikit) takes default, squircle and round.
status (antuikit) takes Badge's five: success, processing, error, warning, default.

// A preset and a theme palette take the same prop.

<Tag color="magenta">magenta</Tag>

<Tag color="fuchsia">fuchsia</Tag>

<Tag color="error" emphasis="subtle" size="small">error</Tag>

A palette name gets the same fill, border and solid treatment as a preset, in both modes. A hex color derives its fill from that one color and does not change in dark mode.

Flags

disabled grays the tag, drops the href and takes the close button out of the tab order.
closable takes a boolean or an object. The object carries closeIcon, disabled and any aria-* or data-* key, which is how you give the button an aria-label.
bordered is deprecated and warns. Use variant="filled", and variant="solid" for the old color="blue-inverse".
There is no iconOnly. Pass an icon with no children and the tag becomes square.

Slots

The props that take your own content.

icon takes any node and renders before the label, in the tag's text color. Pass the kit's Icon so the glyph follows your icon pack.
closeIcon replaces the close glyph. Your own node, here or in the closable object, is used as is, without the kit's spacing, color and hover fade.
avatar (antuikit) takes an image URL, not a node. It renders a decorative <img alt=""> at the start edge, and its corner follows shape.
children is the label. It only sits in the content part when there is an icon, so classNames.content does nothing on a tag without one.

Events

onClose fires before the tag hides, so preventDefault() keeps it, and showing it again is up to you.
Every HTML attribute passes to the root, onClick included. A Tag with onClick gets a click ripple but no keyboard support, so use a Button for an action.

<Tag

color="blue"

closable={{ "aria-label": "Remove filter: React" }}

onClose={(e) => {

e.preventDefault(); // the tag stays mounted

void confirmRemoval();

}}

React

</Tag>

Styling

classNames and styles take the same four keys, one per part. Use them before a descendant selector: a part with a key keeps its name across versions.

<Tag

classNames={{

root: "…",

icon: "…",

content: "…",

close: "…",

}}

item is not one of them. It belongs to Tag.CheckableTagGroup, whose parts are root and item.

A bg-* in your className loses to emphasis="subtle" and to a palette color's fill. Leave emphasis off, or use a preset color, when you style the fill yourself.

A Tailwind utility on one of these keys wins without !important. Setting a component token's CSS variable on the root does not work: style the part instead.

Tag.CheckableTag

The kit's Tag does not re-export Tag.CheckableTag or Tag.CheckableTagGroup. They have no color or variant for the kit to extend, so import them from antd.

import { Tag as AntdTag } from "antd";

import { Tag } from "@/components/ui/tag";

// A toggle. `checked` is required.

<AntdTag.CheckableTag checked={checked} onChange={setChecked}>

{checked ? "Following" : "Follow"}

</AntdTag.CheckableTag>

// A group: one choice by default, several with `multiple`.

<AntdTag.CheckableTagGroup options={OPTIONS} value={value} onChange={setValue} />

<AntdTag.CheckableTagGroup multiple options={OPTIONS} value={values} onChange={setValues} />

It is a control, not a label: role="checkbox", aria-checked, its own tab stop, and the primary color when checked. Space toggles it and Enter does not. See the Accessibility tab before you ship a group of them.