Advanced Ant UI Kit & Design System

Usage

When to reach for Tag, how to pick its color and loudness, and the traps to avoid.

When to use

A Tag is a short label for a category, a status or a keyword, next to the thing it describes. It is not a control: it renders a plain <span> (an <a> with href), with no role and no tab stop.

Categories and keywords on one row: the labels on an issue, the topics on a post, the languages in a repository.
A state that belongs to one row: Draft, Deploying, 3 failing.
Filters the reader has applied, each one removable with closable.
A person, with avatar for the face and the label for the name.

Use something else when:

It is a count on the corner of something else. That is a Badge, which caps the number at 99+.
Clicking it does something: applying, navigating, opening a menu. That is a Button. A Tag with an onClick has no role, no focus ring and no keyboard support.
The reader picks one of a short, fixed set to change the view. That is Segmented. For a long or user-defined set of chips, use Tag.CheckableTag.
It is a message with a dismiss button. That is an Alert.

Color, and what a color is allowed to mean

color takes four kinds of value, and they are not interchangeable.

The five status names (success, processing, error, warning, default). Keep them for state, matching every Alert, Badge and Result on the page.
antd's presets (blue, green, gold and the rest). They mean nothing until you give them a meaning, and that meaning has to hold across the product.
Palette names work like presets. A palette from your theme (the default theme adds amber, emerald, teal, sky, indigo, violet, fuchsia, rose and grays like slate and zinc) works with every variant and in dark mode.
A hex color does not follow the theme. color="#f50" derives the fill from that one color, the same in light and dark mode. When the color belongs to your brand, add it to the theme as a palette.

Give each color one meaning, everywhere. Pick the color from the value (a fixed map, or a hash of the label), so the same label has the same color on every screen.

Do not use a status color for a category. A red “Marketing” tag reads as a failure.
Use as few colors as the screen needs. When every tag is a different color, color stops saying anything.
Never let color carry the meaning alone. The word has to say it too. See the Accessibility tab.
color="blue-inverse" and its siblings are deprecated and warn. Use variant="solid".

How loud: variant, emphasis, size

variant, emphasis and size decide how much attention a tag takes, and they combine.

filled is the default: a tint of the color under dark text.
outlined adds a border of the same color. It suits a row of tags above a dense list.
solid fills with the color under light text. It is the loudest, so use at most one per view.
emphasis="subtle" uses a neutral fill and no border and keeps the colored text, for a tag that should be present without competing.
For a loud tag, use variant="solid". emphasis has only default and subtle. On a solid or disabled tag, subtle wins over a fill class in your className, so leave emphasis off when you style the fill yourself.
size="small" is a shorter tag with smaller text, for metadata at the end of a row. Do not mix sizes in one row.

Pick one value for each of these per surface and keep it. When they change from tag to tag, the reader cannot tell what the difference means.

Shape

default has the same corner as the form fields around it, and reads as a label.
round is a pill. It reads as a chip, which suits people, keywords and anything the reader can remove.
squircle needs Chromium 139 or later. Other browsers show the default corner, so do not use the shape to tell tags apart.

Use one shape per surface. An avatar follows the tag's shape on its own.

Closable tags

closable puts a close button after the label, at the trailing edge, which flips under RTL.

Closable means remove this from the set: an applied filter, a recipient, a label on an issue. It does not mean dismiss a message.
Make a tag closable only when the reader may remove it.
The close button takes the tag's color. A closeIcon of your own replaces it as is, without the kit's spacing and hover fade. Pass closable an object to give the button an aria-label, and call e.preventDefault() in onClose to keep the tag.
Keeping the tag with preventDefault() is how you ask for confirmation, offer an undo or wait for a server call that can fail.
A disabled tag still shows its close button, inert. Leaving it out is usually clearer.

Icons, dots and avatars

icon takes any node and sits before the label, in the tag's text color. Pass the kit's <Icon> so it follows your icon pack.
One glyph per tag, at the start. An icon, an avatar and a close button crowd a small tag.
Name an icon-only tag. Pass icon and no children for a square tag, and set title or aria-label so the glyph has a name.
status adds a Badge dot. Use it when the tag is the state, not as decoration on a category. statusColor gives the dot its own color, and without status it shows a plain dot.
The avatar image is decorative. It renders with an empty alt, so the label has to name the person. Use avatar or icon, not both.
Make the tag the link with href. A <a> nested inside a tag drops to the plain text color. Pass href to the Tag and it keeps its own color.

Checkable tags

Import CheckableTag from antd. The kit's Tag does not re-export Tag.CheckableTag or Tag.CheckableTagGroup, so use antd's Tag for them.

It is a toggle, not a label: role="checkbox", in the tab order, filled with the primary color when checked. Use it when the tags are the control: topics to follow, facets to filter by.
checked is required, so you hold the state.
The group allows one choice by default and several with multiple. A single-choice group still announces each option as a checkbox, so use a Radio group where only one may be picked.
Do not mix checkable and plain tags in one row. They look the same at rest.

Spacing a row of tags

A Tag has no outer margin, so two tags side by side touch. Space the row, not the tags.

Use flex flex-wrap items-center gap-2, or Space or Flex.
Do not add a margin to each tag. It doubles the gap and leaves one after the last tag.
Tags wrap, so the row needs flex-wrap and a vertical gap too.
A long label makes the tag wider instead of wrapping. To truncate it, wrap the label in your own span with a max width, since the tag's content part only exists when it has an icon.

Tag

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