Skip to content
lib components / Visuals

Badge

Use this component to highlight the status, category, or numeric value of an item.

ExamplesPropertiesGuidelinesNotable 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

<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 last three types (highlight1, highlight2 and highlight3) share the same, more general purpose. Use these when the other types don’t apply to your use case. For example, you might have items on a page that refer to accessibility issues. You could then use the three highlight types to communicate the conformance level (A, AA, or AAA) of each accessibility issue.

TypeMeaning/Purpose

neutral

Something is neither important, unimportant, negative or positive.

subtle

Something is relatively unimportant.

positive

Something has gone well or is going well.

warning

Something requires attention, but isn’t critical.

critical

Something is critical and requires attention.

negative

Something has gone wrong.

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.

Neutral

Subtle

Positive

Warning

Critical

Negative

Highlight1

Highlight2

Highlight3

<Badge type="neutral">Neutral</Badge> <Badge type="subtle">Subtle</Badge> <Badge type="positive">Positive</Badge> <Badge type="warning">Warning</Badge> <Badge type="critical">Critical</Badge> <Badge type="negative">Negative</Badge> <Badge type="highlight1">Highlight1</Badge> <Badge type="highlight2">Highlight2</Badge> <Badge type="highlight3">Highlight3</Badge>

#Variants

Set the variant property to light if a badge needs to be less visually prominent. For example, when more important UI elements need to attract the user's attention, instead. Another use case is when there are a lot of badges on a page (for example, in every row of a table). That may result in the badges collectively becoming visually dominating.

Neutral

Subtle

Positive

Warning

Critical

Negative

Highlight1

Highlight2

Highlight3

<Badge type="neutral" variant="light"> Neutral </Badge> <Badge type="subtle" variant="light"> Subtle </Badge> <Badge type="positive" variant="light"> Positive </Badge> <Badge type="warning" variant="light"> Warning </Badge> <Badge type="critical" variant="light"> Critical </Badge> <Badge type="negative" variant="light"> Negative </Badge> <Badge type="highlight1" variant="light"> Highlight1 </Badge> <Badge type="highlight2" variant="light"> Highlight2 </Badge> <Badge type="highlight3" variant="light"> Highlight3 </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

Badge

Badge

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

#Screen reader only

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 orange 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.

Warning:

Missing

42

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

#Properties

badge

PropertyDescriptionDefinedValue
childrenOptional
elementText displayed inside the badge
typeOptional
"critical" | "highlight1" | "highlight2" | "highlight3" | "negative" | "neutral" | "positive" | "subtle" | "warning"Controls the color of the badge - defaults to "neutral"
variantOptional
"dark" | "light"Controls the visual style of the badge - defaults to "dark"
sizeOptional
"large" | "medium" | "small"Controls the size of the badge - defaults to "medium"
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#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 highlight type badges consistently. For instance, always use highlight1, highlight2, and highlight3 for accessibility conformance levels A, AA, and AAA, respectively.
  • Set the variant property to light if a badge needs to attract less attention.
  • 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.

#Do not use when

The badge needs to be interactive. Instead, use a tag (hasn't yet been added to Fancy).

#Accessibility

Sometimes, the meaning of a badge is unclear if you can't see its color or position within the UI. Use a SrOnly component to supply color-blind and non-sighted users with the critical visual information they’re missing out on.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • 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.