lib components / Visuals

Badge

Allow users to quickly identify the status, category, or numeric value of an item through a visual highlight

Examples Properties Guidelines Notable Changes

import { Badge } from "@siteimprove/fancylib";

#Examples

The Badge component features a few properties for adjusting its appearance. The following sections showcase these properties and explain when and how to use them.

#Default

This is the default appearance of the Badge component. It’s type, variant, and size props are by default set to neutral, dark, and medium, respectively.

Badge

CodeHTML output

Theme: agentic-ai-2025

<Badge>Badge</Badge>

#Types

Use the type property to change the color of a badge. Every color has a specific semantic meaning or purpose. Consult the table below to find out which badge type suits your use case.

The four highlight types (highlight1, highlight2, highlight3, and highlight4) share the same, more general purpose.

Use the custom type when the other types don’t apply to your use case. See examples below.

Type	Meaning/Purpose
Positive	Something has gone well or is going well.
Neutral	Something is in a standard state with no action required.
Warning	Something requires attention.
Negative	Something has gone wrong.
Subtle	Supporting information that provides context without demanding focus.
Highlight1	Something has a certain status or belongs to a certain category.
Highlight2	Something has a certain status or belongs to a certain category.
Highlight3	Something has a certain status or belongs to a certain category.
Highlight4	Something has a certain status or belongs to a certain category.
Custom	Specify custom background and foreground colors.

Positive

Neutral

Warning

Negative

Subtle

Highlight1

Highlight2

Highlight3

Highlight4

Custom

CodeHTML output

Theme: agentic-ai-2025

<Badge type="positive">Positive</Badge>
<Badge type="neutral">Neutral</Badge>
<Badge type="warning">Warning</Badge>
<Badge type="negative">Negative</Badge>
<Badge type="subtle">Subtle</Badge>
<Badge type="highlight1">Highlight1</Badge>
<Badge type="highlight2">Highlight2</Badge>
<Badge type="highlight3">Highlight3</Badge>
<Badge type="highlight4">Highlight4</Badge>
<Badge type="custom" backgroundColor={ColorYellow} foregroundColor={ColorBlue}>
	Custom
</Badge>

Since the children prop is ReactNode you can easily add icons to a Badge. Icons should be positioned in front of the label and the spacing between the icon and label should be SpaceXxSmall (= 4px). See example implementation below.

Positive

Neutral

Warning

Negative

Subtle

CodeHTML output

Theme: agentic-ai-2025

<Badge type="positive" style={{ gap: SpaceXxSmall }}>
	<Icon>
		<IconSuccess />
	</Icon>
	Positive
</Badge>
<Badge type="neutral" style={{ gap: SpaceXxSmall }}>
	<Icon>
		<IconInfo />
	</Icon>
	Neutral
</Badge>
<Badge type="warning" style={{ gap: SpaceXxSmall }}>
	<Icon>
		<IconWarning />
	</Icon>
	Warning
</Badge>
<Badge type="negative" style={{ gap: SpaceXxSmall }}>
	<Icon>
		<IconError />
	</Icon>
	Negative
</Badge>
<Badge type="subtle" style={{ gap: SpaceXxSmall }}>
	<Icon>
		<IconBlock />
	</Icon>
	Subtle
</Badge>

#Custom type

Use the custom type together with the backgroundColor and foregroundColor props to specify custom background and foreground colors. By default the foreground color of a badge is --color--white.

In the example below we see how to use the badge component to show the conformance level for accessibility issues, as well as a badge for ARIA and a badge version of the Siteimprove logo.

AAA

ARIA

CodeHTML output

Theme: agentic-ai-2025

<Badge type="custom" backgroundColor={ColorPink}>
	A
</Badge>
<Badge type="custom" backgroundColor={ColorPurpleDark}>
	AA
</Badge>
<Badge type="custom" backgroundColor={ColorTealDarker}>
	AAA
</Badge>
<Badge type="custom" backgroundColor={ColorBlue}>
	ARIA
</Badge>
<Badge type="custom" backgroundColor={ColorBlueDark}>
	S
</Badge>

#Sizes

Use the size property to adjust the size of a badge. The default size is medium and should be used in most cases. Use small when space is limited, such as in the Page Report. Use large when a badge needs to attract extra attention or visually match its item. Badges placed next to each other should all have the same size (so not like in the example below).

Badge

CodeHTML output

Theme: agentic-ai-2025

<Badge size="small">Badge</Badge>
<Badge size="medium">Badge</Badge>
<Badge size="large">Badge</Badge>

To understand the meaning of a badge, you sometimes need more than just its label. You might need to see its color or placement within the UI as well. Use the SrOnly component to supply color-blind and non-sighted users with critical visual information they’re missing out on.

For example, you might not realize that a badge labelled "Missing" is warning you about something, if you can't see its yellow color. Alternatively, if you can't see the position of a badge, it might be unclear that its number refers to how many occurrences have been detected of a certain accessibility issue.

The examples below show how to use the SrOnly component to address such problems.

Missing

CodeHTML output

Theme: agentic-ai-2025

<Badge type="warning">
	<SrOnly>Warning:</SrOnly> Missing
</Badge>
<Badge>
	42 <SrOnly>occurrences</SrOnly>
</Badge>

#Properties

badge

CodePropsHTML output

Theme: agentic-ai-2025

Property	Description	Defined
childrenOptional	`element`Text displayed inside the badge	YesNo
typeOptional	`"custom" \| "highlight1" \| "highlight2" \| "highlight3" \| "highlight4" \| "negative" \| "neutral" \| "positive" \| "subtle" \| "warning"`Controls the color of the badge - defaults to "neutral"	YesNo
sizeOptional	`"large" \| "medium" \| "small"`Controls the size of the badge - defaults to "medium"	YesNo
backgroundColorOptional	`string`Specify custom background color	YesNo
foregroundColorOptional	`string`Specify custom foreground color	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Guidelines

#Best practices

Use a badge to highlight the status, category, or numeric value of an item.
Choose a badge type (color) based on its associated semantic meaning.
Only use a highlight badge if the other, more semantically specific, types don’t fit your use case.
Use the custom type badge with the correct foregroundColor and backgroundColor for accessibility conformance levels A, AA, and AAA, as well as ARIA and S (Siteimprove). See examples above.
Use small badges when space is limited, such as in the Page Report.
Use large badges when they need to attract extra attention or visually match their item.
Use the same size for badges placed next to each other.
Position badges so that it's clear which item they're related to.
Only add icons in front of the label with 4px spacing (SpaceXxSmall).

Keep badge labels short — no more than two words.
Use past tense for verbs ("Updated", not "Update").
Capitalize the first letter of badge labels.

#Notable Changes

#Version 0.0.x

The Text property has been removed and the Badge component is no longer self-closing. Instead, you now wrap the label (or other content) in Badge tags.
The color property has been renamed to type. Its blue (default), green, red, and yellow values have been replaced with neutral (default), subtle, positive, warning, critical, negative, highlight1, highlight2, and highlight3.
The small property has been renamed to size. Instead of being a boolean, it now offers the values small, medium (default), and large.
The fill property has been removed.

Badge

#Examples

#Default

#Types

#Using icons

#Custom type

#Sizes

#Properties

#Guidelines

#Best practices

#Do not use when

#Accessibility

#Writing

#Notable Changes

#Version 0.0.x