Badge draws user focus to an interactive element on the page that has new or updated items. It’s often used to notify users of unread messages or alerts.

• When an element on the page has new or updated items, it displays Badge, overlapping its top right corner.
• The number inside Badge indicates the number of items.
• To view the items, the user clicks the page element, which opens a separate page or expands the collapsed content to display the items.
• Once all items have been opened or viewed, Badge disappears from the initial page, indicating that there are no new or updated items.

• To notify users that there’s a specific number of new or updated items in a location
• To draw attention to a navigation element on the page with minimal disruption

• To notify users about new or updated items in general without indicating how many (Badge requires a number)
• For notifications that need messaging to explain them (Badge doesn’t include any message text)

Use Badge with interactive elements like navigation elements, icons, or cards that lead users to an area with new, unread, or updated items. Badge indicates how many of these items users will find in that area. For example, an inbox link with a Badge could lead to a separate page with new messages, and a collapsed table with a Badge could be expanded to reveal rows with updated data.

Numbers

Badge displays numbers only. There’s no limit on how large the number can be, though numbers more than 4 digits long may look awkward.

You can set a maximum number for Badge. Any value that exceeds the cutoff is displayed as the maximum number with a plus sign (e.g., if the max is 30, then any count over 30 is displayed as “30+”).

Dismissing Badge

Users can’t dismiss Badge manually. Badge is dismissed after users view or read all the counted items. This behavior isn’t built in and must be implemented. There are generally 2 ways a user can mark all items as read and dismiss a Badge:

• Click or activate the interactive element Badge is attached to and view the list of unread items
• Click or activate the interactive element Badge is attached to and then open each unread item individually

Badge is typically not displayed when all items have been read. It does include an option to show a count of “0”, though, if this fits your use case.

Color

Badge’s default color draws user attention to unread items. Technically, Badge is available in all of Forge’s alert type colors (see the Forge alert color palette). However, using color alone to convey alert type isn’t accessible for all users, so we strongly encourage you to use Badge’s default color only.

No additional information for this component.

No additional information for this component.

The content in Badge can’t be customized. Item counts are represented as a number only (with the “+” character appended if a maximum count is applied).

No specific tips for this component.

Implementation links

Badge directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook-lts.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Badge } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Badge from '@athena/forge/Badge';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Badge from '@athena/forge/dist/Badge';