## Overview `` elements display a small amount of color-categorized metadata. They're ideal for getting a user's attention. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/badge?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/badge) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/badge?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/badge) ```bash yarn add @spectrum-web-components/badge ``` Import the side effectful registration of `` via: ```js import '@spectrum-web-components/badge/sp-badge.js'; ``` When looking to leverage the `Badge` base class as a type and/or for extension purposes, do so via: ```js import { Badge } from '@spectrum-web-components/badge'; ``` ### Anatomy A badge is made up of the following parts: - **Icon**: an `` element can be used to display an icon within the badge. - **Label**: text can be displayed within the badge by using the default slot. Badges can contain either a label, an icon, or both. ```html demo Label only Icon and label ``` ### Options It is not recommended to make badges interactive. Consider using a different component if you need interactivity, such as buttons, tags, or links. #### Sizes Small ```html demo
Label Icon and label
``` Medium ```html demo
Label Icon and label
``` Large ```html demo
Label Icon and label
``` Extra Large ```html demo
Label Icon and label
``` #### Variants The `` can be customized with either semantic or non-semantic variants. Badges are intended as display elements (like status lights), so avoid using badges for critical actions. Semantic When badges have a semantic meaning, they use semantic colors. Use these variants for the following statuses: - **Positive**: approved, complete, success, new, purchased, licensed - **Informative**: active, in use, live, published - **Negative**: error, alert, rejected, failed - **Neutral**: archived, deleted, paused, draft, not started, ended ```html demo
Accent Neutral Informative Positive Negative Notice
``` Non-semantic When badges are for color-coded categories, they use non-semantic colors. Non-semantic variants are ideally used for when there are 8 categories or less. ```html demo
Seafoam Indigo Purple Fuchsia Magenta Yellow Gray Red Orange Chartreuse Celery Green Cyan Blue
``` #### Fixed positioning `` can be displayed as if it is "fixed" to the edge of a UI. The `fixed` attribute can be leveraged to alter the border rounding based on the position you would like to achieve. Fixed positioning options include `block-start`, `block-end`, `inline-start`, and `inline-end`. ```html
None block-start inline-end block-end inline-start
``` ### Behaviors Badges are not interactive by default. When a badge's label is too long for the available horizontal space, it wraps to form another line. Text wrapping can be enforced when a `max-inline-size` is applied to the badge. If there is no room for a second line of text, the badge should truncate and include a tooltip to expose the full text upon hover. ```html demo Wikipedia is the best thing ever. Anyone in the world can write anything they want about any subject so you know you are getting the best possible information. Wikipedia is the best thing ever. Anyone in the world can write anything they want about any subject so you know you are getting the best possible information. ``` ### Accessibility
Do ✅ Don't ❌ Use badges for status indication Use badges for critical actions Use visible labels most often Overwhelm a user with too much critical information Use icon-only badges with aria-label Use badges for supplemental information
#### Always include a label Badges should always have a label for accessibility and clear comprehension. When the label is not defined, a badge becomes icon-only. If a visible label isn't specified, an `aria-label` must be provided to the icon for accessibility. An icon-only badge is best for very small spaces, and it should include a tooltip on hover to provide more context for the icon's meaning. Remember that a tooltip does not replace an accessible label. ```html demo Labels are important ``` #### Keyboard interactions - Tab: Places focus on the badge if it is interactive. - Space or Enter: Filters results by the selected badge or performs the action associated with the badge. #### Don't override semantic colors The badge's variants provide semantic meaning through both color and ARIA attributes, ensuring that information is not conveyed through color alone.