Badge

The <nys-badge> component provides a visual indicator of text values like categories.

Copy Code
<nys-badge label="Basic badge"></nys-badge>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.


Accessibility

  • The <nys-badge> text should be concise and immediately understandable (e.g., "New", "Beta", "Admin").

  • Color Coding: Use color intentionally (e.g., red for errors, green for success).

  • Size & Placement: It should be visible but not overpower the main content.

  • There are no visual styles on badge (e.g., hover effects, underlines, cursor pointer) that make the badge appear clickable or interactive, it is not.

  • Uses readable font sizes (12px for small, 14px for medium).

  • Has proper color contrast

  • The <nys-badge> component is read by screen readers appropriately.

  • Always position <nys-badge> so that it's easy to understand what content it's related to.

    Additional accessibility test and build content is coming soon, in a new format.


Options

Intent

Below are the available badge intents, each showcasing its unique style and purpose. The default intent is neutral.

Copy Code
<nys-badge label="Neutral" prefixIcon></nys-badge>
<nys-badge label="Error" intent="error" prefixIcon></nys-badge>
<nys-badge label="Warning" intent="warning" prefixIcon></nys-badge>
<nys-badge label="Success" intent="success" prefixIcon></nys-badge>

Variant

Add variant="strong" for badges on a raised surface or for more emphasis.

Copy Code
<nys-badge label="Neutral" variant="strong" prefixIcon></nys-badge>
<nys-badge label="Error" intent="error" variant="strong" prefixIcon></nys-badge>
<nys-badge label="Warning" intent="warning" variant="strong" prefixIcon></nys-badge>
<nys-badge label="Success" intent="success" variant="strong" prefixIcon></nys-badge>

Icons

Badge can include icons as either a prefix or suffix. The icons can be specified using the prefixIcon or suffixIcon attributes. Pass in the attribute as a boolean to use the default icon, or pass in a string to use a specific icon. Icons do not appear by default and must be explicitly specified.

Copy Code
<nys-badge label="Default neutral" prefixIcon></nys-badge>
<nys-badge label="Default neutral" suffixIcon></nys-badge>
<nys-badge label="Custom neutral" prefixIcon="check"></nys-badge>
<nys-badge label="Custom neutral" suffixIcon="check"></nys-badge>

Size

Badge is available in two sizes: md and sm. The size can be specified using the size attribute. The default size is md.

Note: Do not mix sizes within a group of badges.

Copy Code
<nys-badge label="Medium"></nys-badge>
<nys-badge label="Small" size="sm"></nys-badge>

Prefix Label

Badge can include a prefix label, which is a short text that appears before the main label. The prefix label can be specified using the prefixLabel attribute.

Copy Code
<nys-badge label="Stable" prefixIcon="code"></nys-badge>
<nys-badge prefixLabel="WCAG 2.2" label="AA" intent="success" prefixIcon></nys-badge>

Usage

When to use this component

  • To indicate the status of an item, such as "new", "updated", or "beta".
  • To provide additional context or information about an item without cluttering the interface.

When to consider something else

  • When the information is too complex to be conveyed in a small badge.
  • When the badge would not add significant value to the user experience.

Do

  • Keep badge labels short -- one or two words like "New", "Beta", or "Updated".
  • Use the intent property to match the badge's visual style to its meaning (e.g., success for positive statuses, warning for caution).
  • Place badges near the element they describe so the relationship is clear.
  • Use the prefixIcon or suffixIcon attributes to reinforce meaning when the label alone may be ambiguous.
  • Apply the strong variant when the badge appears on a raised surface or needs extra emphasis.

Don't

  • Don't use badges as interactive elements -- they are not buttons or links.
  • Don't pack long sentences or multiple values into a single badge label.
  • Don't mix badge sizes within the same group; pick either md or sm and stay consistent.
  • Don't rely on color alone to convey meaning; always include a text label.
  • Don't stack multiple badges on a single element unless each communicates a distinct, necessary status.

Properties

Property Type Default
id String ""
label String ""
name String ""
size "md", "sm" "md"
intent "neutral", "error", "success", "warning" "neutral"
variant "strong" ""
prefixLabel String ""
prefixIcon String | boolean —
suffixIcon String | boolean —

Style Overrides

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.


Events

This component does not emit any custom events.

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: May 28, 2026