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 NYSDS web components in your project? Try using the CSS Variables instead.


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>

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.

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>

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.

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>

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.

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>

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.


Usage

When to use this component

  • To display a small piece of information that is related to another element.
  • To draw attention to new, important content.
  • 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.
  • When the badge would clutter the interface or distract from more important content.
  • As a link to another page or action, as badges are not interactive elements.

Do

  • To display a small piece of information that is related to another element.
  • To draw attention to new, important content.
  • 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.

Don't

  • 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.
  • When the badge would clutter the interface or distract from more important content.
  • As a link to another page or action, as badges are not interactive elements.

Accessibility

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


Properties

Property Type
id String
label String
name String
size String "md", "sm"
intent String "neutral", "error", "success", "warning"
prefix String
prefixIcon String
suffixIcon String

CSS Variables


Events

Suggest a New Component

Do you have an idea for a new NYSDS 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: August 22, 2025