User Interface (UI)

Let's start with how a tag looks: its parts, its sizes, its icon, how it shows its states and the variables that restyle each part.

Anatomy

Every tag has a container and a label. The leading icon renders when you give it one, and the remove button when the tag is removable, as long as it's neither disabled nor read-only. The link and the remove button sit side by side, never one inside the other, since HTML doesn't allow a button inside a link (see Don't nest interactive elements). You can see the order of the parts in the DOM contract.

Sizes

A Tag has the Input's five size names, and at each one it's as tall as the Select's tags at that size, so a tag on its own looks the same as one in a Select. We recommend size over setting a height, since it scales the text and the remove button together.

<Tag size="xs" label="Bug" removable onRemove={remove} />
<Tag size="sm" label="Bug" removable onRemove={remove} />
{/* …md, lg and xl */}

Heights are minimums, so a tag grows with larger text rather than clipping it. The remove button is as wide as the tag is tall, and at every size it takes a press over at least 24 × 24px, which Contrast and size explains.

Icons

A tag can have an icon before its label, like a label's symbol on an issue, which helps people scan a row of tags. The leading slot takes it, and the Tag sizes it to the text with --tag--icon--size.

<Tag label="Bug" leading={<BugIcon />} />
<Tag label="Feature" leading={<SparklesIcon />} />
<Tag label="Docs" leading={<BookOpenIcon />} />

Icons are decoration, so they're hidden from assistive technologies, and the label alone names the tag (WCAG 1.1.1). Keep it that way, since an icon that means something the label doesn't say is lost on anyone who can't see it. The Select's tags take their icon through a slot called icon, because it's the option's icon there, shown in the panel too. On its own, the Tag calls it leading, like the Button and the Input.

States

A plain tag has no hover or focus, since there's nothing to press. A tag that's a link, or that's removable, has hover and focus on the parts people press, and any tag can be disabled or read-only.

<Tag label="Bug" />
<Tag label="Bug" href="/labels/bug" />
<Tag label="Bug" removable onRemove={remove} />
<Tag label="Bug" href="/labels/bug" removable disabled />
<Tag label="Bug" href="/labels/bug" removable readonly />

A link tag has a border, so people can tell it from a plain tag without relying on its colour, which colour blind people may not see (WCAG 1.4.1). The border is drawn inside the tag, so a link tag is the same size as a plain one, and as the Select's tags. None of the states change the tag's size or position, so a row of tags doesn't shift as the pointer moves along it, and you'll find how they behave under Every state.

Tokens

The Tag's look comes from variables on its root, which you can set from a class. Tokens are named as token paths: --tag--… for the tag, then a group per part or state, like --tag--icon--… and --tag--link--…. They're in the components layer, so a class of yours wins without any specificity tricks.

It reads --color--neutral-text and --color--focus from your theme. A Tag at a size has the same height, padding, radius and font size as the Select's tags at that size, and each of their tokens has a Tag token with the same job. The one default that differs is the text colour: a Select's tag inherits it from the field, while a Tag sets --color--neutral-text itself, since it isn't inside one.

The label has a contrast of at least 4.5:1 against the tag's background, which is the text colour at 10% over the page. With our reference tokens, from the Tailwind CSS palette, that's 12.3:1 on white and 10.9:1 on zinc-900. A link tag's border is the text colour at 55%, like the Input's, which comes to 3.5:1 against white and 5:1 against zinc-900, so people can see it's there (WCAG 1.4.11). The sections below restyle each part, with its variables and, where it has one, its slot.

Container and label

The root draws the tag, so its tokens set the background, the text colour and the radius. The default slot changes what the label says, and the remove button keeps its name, which comes from label.

<Tag className="brand" label="Bug" removable onRemove={remove} />

.brand {
  --tag--radius: 1rem;
  --tag--background: var(--color--primary);
  --tag--color: var(--color--primary-contrast);
}

If you colour tags by what they mean, like a label's colour on an issue, set --tag--background and --tag--color from a class per category, and check each pairing for 4.5:1. The colour can't be the only way people tell two tags apart, so the label still has to say it (WCAG 1.4.1).

Leading icon

The leading slot takes the icon, and --tag--icon--size and --tag--gap set its size and the space after it.

<Tag className="brand" label="Bug" leading={<TagIcon />} removable onRemove={remove} />

.brand {
  --tag--icon--size: 0.875rem;
  --tag--gap: 0.375rem;
}

Remove button

The remove slot changes the remove button's icon, and the button and its name stay, so a screen reader still says "Remove Bug". --tag--hover--background sets what shows behind it on hover.

<Tag className="brand" label="Bug" removable remove={<CircleXIcon />} onRemove={remove} />

.brand {
  --tag--hover--background: color-mix(in srgb, var(--color--error) 20%, transparent);
}

UI Checklist

FAQ