Badge

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Badge signals status, category, or metadata in a compact, glanceable format, displaying short pieces of information with visual emphasis via color and size variants.

Props

Name	Type	Default	Description
`appearance`	`BadgeAppearance`	—	Tinted wash or opaque solid. Defaults to {@link BadgeAppearance.Tinted}. A static badge keeps the size radii either way. Tinted wash or opaque accent solid. Defaults to {@link BadgeAppearance.Tinted}. A static badge keeps the size radii either way. Not a prop on Insight badges; the border is not a tinted or solid fill.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	A labeled badge is named by `text`. Use the icon-only variant for `aria-label`. Accessible name when there is no visible text. Required. The glyph and `status` are decorative and do not replace this name.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`disabled`	`boolean`	—	Inert state: native `disabled` on a `button`, an inert link host on an anchor.
`dismissLabel`	`LocalizedMessage`	—	Accessible name of the dismiss button, for example "Remove night shift filter".
`href`	`string`	—	Navigation target. Makes the badge an anchor.
`icon`	`Glyph`	—	Decorative glyph shown before the text. It is `aria-hidden`; the text stays the name. Omit `text` and pass `aria-label` for an icon-only badge. Glyph that is the badge content. Decorative and `aria-hidden`. Pass one from `@prepared911/ui/icons/*`.
`intent`	`BadgeIntent`	—	Status or neutral intent for shell paint and label color. Defaults to {@link BadgeIntent.Neutral}. Not a prop on Beta badges; shell paint does not vary by intent (Decision BD-8). Not a prop on Insight badges; the border does not vary by intent.
`onClick`	`MouseEventHandler<HTMLButtonElement> \| MouseEventHandler<HTMLAnchorElement>`	—	Activates the badge. Makes it a `button`. Called on activation, for example to track navigation.
`onDismiss`	`MouseEventHandler<HTMLButtonElement>`	—	Called when the dismiss button is activated. Its presence makes the badge interactive and pill-shaped.
`ref`	`((instance: HTMLSpanElement \| null) => void \| (() => VoidOrUndefinedOnly)) \| RefObject<HTMLSpanElement \| null> \| ... 5 more ...`	—	Ref to the rendered `span`. Ref to the rendered `button`. Ref to the rendered anchor. Ref to the rendered shell `span`.
`selected`	`boolean`	—	Toggle state for a filter-like badge. Writes `aria-pressed`, so it needs a boolean on every render.
`size`	`BadgeSize`	—	Padding, gap, corner radius, and type role. Defaults to {@link BadgeSize.Regular}. Padding and corner radius of the square chip. Defaults to {@link BadgeSize.Regular}.
`status`	`BadgeStatus`	—	Not a prop on a labeled badge. A status mark belongs on an icon-only badge. Optional status mark beside the glyph: a status dot or a status glyph. Decorative, so it does not replace `aria-label`.
`text`	`LocalizedMessage \| DisplayValue`	—	Visible label. Meaning lives in this string; color is not the only signal. Pass copy as a {@link LocalizedMessage}. Pass a value the caller computed, such as a count, a duration (`5/s`, `12 ms`), a date or a status read from data, as a {@link DisplayValue} (`toDisplayValue`). It is the accessible name either way. Not used. An icon-only badge has no visible label.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`type`	`BadgeType`	—	Soft chip with corner radii by size. Defaults to {@link BadgeType.Default}. Accent badge treatment for beta or preview labels. Strong border, no fill, regular caption label.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Default

Use when no specific semantic meaning is required or the badge should be low‑attention.

Semantic colors

Semantic colors convey meaning without requiring users to read the label.

Info

Marks informational context or items that merit awareness.

Success

Indicates success, completion, or a positive state.

Warning

Highlights caution or intermediate states that need attention but are not errors.

Error

Signals failure or an error state. Use sparingly.

Accent colors

Accent colors add variety, useful for categorization or visual grouping.

Lime

A lively alternative to Success. Works for growth or environmental contexts.

Cyan

Useful when many categories need visual differentiation.

Purple

Useful when many categories need visual differentiation.

Violet

Useful when many categories need visual differentiation.

Pink

Useful when many categories need visual differentiation.

Sizes

Use size to reflect prominence and content density.

Small

For tight spaces, lists, or when the badge supplements other content.

Regular

Default size balancing readability and space.

Shape

The current component renders a rounded rectangle.

Rounded (current)

Best for read‑only semantic indicators with no click interactivity.

Badge (future)

Consider for interactive patterns like tags or table filters where clicking changes state.

With icon

Add an icon for extra context or quick recognition.

Icon only

Icon-only badges are square at every size. Provide aria-label so the meaning is announced without visible text; the same value appears in a tooltip on hover.

Small

Regular

Large

Badge / Usage

Badge / Accessibility

On this page

Badge

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Badge signals status, category, or metadata in a compact, glanceable format, displaying short pieces of information with visual emphasis via color and size variants.

Props

Name	Type	Default	Description
`appearance`	`BadgeAppearance`	—	Tinted wash or opaque solid. Defaults to {@link BadgeAppearance.Tinted}. A static badge keeps the size radii either way. Tinted wash or opaque accent solid. Defaults to {@link BadgeAppearance.Tinted}. A static badge keeps the size radii either way. Not a prop on Insight badges; the border is not a tinted or solid fill.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-label`	`LocalizedMessage`	—	A labeled badge is named by `text`. Use the icon-only variant for `aria-label`. Accessible name when there is no visible text. Required. The glyph and `status` are decorative and do not replace this name.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`disabled`	`boolean`	—	Inert state: native `disabled` on a `button`, an inert link host on an anchor.
`dismissLabel`	`LocalizedMessage`	—	Accessible name of the dismiss button, for example "Remove night shift filter".
`href`	`string`	—	Navigation target. Makes the badge an anchor.
`icon`	`Glyph`	—	Decorative glyph shown before the text. It is `aria-hidden`; the text stays the name. Omit `text` and pass `aria-label` for an icon-only badge. Glyph that is the badge content. Decorative and `aria-hidden`. Pass one from `@prepared911/ui/icons/*`.
`intent`	`BadgeIntent`	—	Status or neutral intent for shell paint and label color. Defaults to {@link BadgeIntent.Neutral}. Not a prop on Beta badges; shell paint does not vary by intent (Decision BD-8). Not a prop on Insight badges; the border does not vary by intent.
`onClick`	`MouseEventHandler<HTMLButtonElement> \| MouseEventHandler<HTMLAnchorElement>`	—	Activates the badge. Makes it a `button`. Called on activation, for example to track navigation.
`onDismiss`	`MouseEventHandler<HTMLButtonElement>`	—	Called when the dismiss button is activated. Its presence makes the badge interactive and pill-shaped.
`ref`	`((instance: HTMLSpanElement \| null) => void \| (() => VoidOrUndefinedOnly)) \| RefObject<HTMLSpanElement \| null> \| ... 5 more ...`	—	Ref to the rendered `span`. Ref to the rendered `button`. Ref to the rendered anchor. Ref to the rendered shell `span`.
`selected`	`boolean`	—	Toggle state for a filter-like badge. Writes `aria-pressed`, so it needs a boolean on every render.
`size`	`BadgeSize`	—	Padding, gap, corner radius, and type role. Defaults to {@link BadgeSize.Regular}. Padding and corner radius of the square chip. Defaults to {@link BadgeSize.Regular}.
`status`	`BadgeStatus`	—	Not a prop on a labeled badge. A status mark belongs on an icon-only badge. Optional status mark beside the glyph: a status dot or a status glyph. Decorative, so it does not replace `aria-label`.
`text`	`LocalizedMessage \| DisplayValue`	—	Visible label. Meaning lives in this string; color is not the only signal. Pass copy as a {@link LocalizedMessage}. Pass a value the caller computed, such as a count, a duration (`5/s`, `12 ms`), a date or a status read from data, as a {@link DisplayValue} (`toDisplayValue`). It is the accessible name either way. Not used. An icon-only badge has no visible label.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`type`	`BadgeType`	—	Soft chip with corner radii by size. Defaults to {@link BadgeType.Default}. Accent badge treatment for beta or preview labels. Strong border, no fill, regular caption label.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Default

Use when no specific semantic meaning is required or the badge should be low‑attention.

Semantic colors

Semantic colors convey meaning without requiring users to read the label.

Info

Marks informational context or items that merit awareness.

Success

Indicates success, completion, or a positive state.

Warning

Highlights caution or intermediate states that need attention but are not errors.

Error

Signals failure or an error state. Use sparingly.

Accent colors

Accent colors add variety, useful for categorization or visual grouping.

Lime

A lively alternative to Success. Works for growth or environmental contexts.

Cyan

Useful when many categories need visual differentiation.

Purple

Useful when many categories need visual differentiation.

Violet

Useful when many categories need visual differentiation.

Pink

Useful when many categories need visual differentiation.

Sizes

Use size to reflect prominence and content density.

Small

For tight spaces, lists, or when the badge supplements other content.

Regular

Default size balancing readability and space.

Shape

The current component renders a rounded rectangle.

Rounded (current)

Best for read‑only semantic indicators with no click interactivity.

Badge (future)

Consider for interactive patterns like tags or table filters where clicking changes state.

With icon

Add an icon for extra context or quick recognition.

Icon only

Icon-only badges are square at every size. Provide aria-label so the meaning is announced without visible text; the same value appears in a tooltip on hover.

Small

Regular

Large

Badge / Usage

Badge / Accessibility

On this page