Tag

Overview

Tag displays a user-created classification whose colour is the point — a menu category, a catalog grouping. Unlike StatusBadge, the user's colour tints the whole surface: background, border and text.

That is the entire distinction between the two:

StatusBadge — colour is a hint about the thing you are reading. It stays on the dot.
Tag — colour is the thing you are reading. It tints the surface.

A classification is scanned at a glance among siblings, so the colour has to carry. A status is read down a column, so it must not.

Basic Usage

import { Tag } from '@fsai/shared-ui';

<Tag name={category.name} color={category.color} />

Colour is required

color is a required prop. It is nullable, because a classification's colour is nullable in the database — but you must pass it deliberately.

A Tag exists to show a colour the user picked, and it always renders a dot. Without a colour, every tag draws the same blue dot and implies a coding that is not there. If your label has no colour of its own, use Badge instead.

// ✓ the classification has a colour
<Tag name={category.name} color={category.color} />

// ✗ no colour of its own — this is a Badge
<Tag name={tag.name} color={null} />
<Badge label={tag.name} dot />

This is not hypothetical: the tags table has no colour column, so 15 lead-tag call sites were all drawing the same blue dot for a coding that did not exist. They became badges that keep the dot.

Props

Prop	Type	Default	Description
`name`	`string`	—	Required. The classification name.
`color`	`string \| null`	—	Required. The user's colour. Drives the dot, surface and text.
`textColor`	`string \| null`	derived from `color`	Override for the label colour.
`bgColor`	`string \| null`	derived from `color`	Override for the surface colour.
`className`	`string`	—	Additional classes.

Height and type

Tag derives its height from the type token plus padding and border, like every other badge-shaped element — see Control Heights. Its label sits on text-md.

Known limitation

Contrast is unclamped. The colour comes from a free hex picker and drives both the surface and the text via darkenHex, so a poor choice can hurt contrast. The icon side is safe — IconPicker offers 172 curated icons — but the colour side has no guard yet.

Guidelines

Do use Tag when the user's colour is the classification's coding
Do pass color deliberately, even when it may be null
Don't use Tag for a label with no colour of its own — that is a Badge
Don't use Tag for a lifecycle status — that is a StatusBadge
Don't pin its height

Tag