A badge highlights system generated metadata as an attribute of a larger object.
- Container: Wraps the content.
- Icon (optional): Supports or directly communicates the metadata meaning, always left aligned.
- Text (optional): Conveys the status or other attribute of the metadata.
When to use
- Highlight system generated metadata that provides additional meaning or status to a primary object, like an issue or merge request.
When not to use
- Showing metadata doesn't always require the use of a badge. If it doesn't need to be highlighted consider using a static icon or plain text.
- A badge shouldn't be a standalone, floating element. If it can't be placed within direct relationship to the object it supports, consider using another method that provides more context for the metadata.
- If the metadata is created and applied by a user, or customizable, use a label instead.
- Neutral muted (default): Metadata that requires the least amount of visual emphasis and has a neutral meaning.
- Neutral: Metadata that has a neutral meaning.
- Info: Metadata that's informative or new and also has a neutral meaning.
- Success: Metadata that communicates success or completion with a positive meaning.
- Warning: Metadata that requires attention and a slightly negative meaning.
- Danger: Metadata that indicates a problem and has a negative meaning.
- Tier: Metadata that indicates which product tier an entity belongs to
- Small: A small badge is ideal in condensed parts of the UI where space is limited.
- Medium (default): Use the medium size where content has breathing room. The medium size also works well to provide sufficient affordance when only an icon is used.
- Large: A large badge is used in headers or titles where there is ample space or the metadata needs additional prominence.
- A badge is static (non-interactive) by default.
- A badge should link to the object it refers to if the user isn't seeing the most detailed state of that object (for example, the object's detail page).
- Information can be represented by an icon, text, or both together.
- Avoid long text strings.
- When text overflows the width, it's truncated and aided by a tooltip (content doesn't wrap).
- Text can be emphasized with bold weight, but use sparingly.
- Text can contain not only words, but also numbers which act as counters (for example, a number badge in a tab).
- When only using an icon, provide a tooltip with a brief explanation.
- When a badge only has an icon, the icon must use
aria-labelwith text that identifies the metadata.
- When an icon is present with text it must use
aria-hidden="true"to avoid being announced by a screen reader.
- When a badge is used as meta information to support content it's inline with, ensure that its meaning is clear. If necessary, add
sr-onlytext after the badge. For example,
<gl-badge>9</gl-badge><span class="sr-only">to-do's</span>clarifies what "9" quantifies.
- If a badge isn't inline with the content it supports, use
aria-describedby="badgeID"to associate the content with the badge, where
badgeIDis the unique ID of the badge. Note that
aria-describedbysupport is mostly on focusable elements and headings.
Other terms that are commonly used to refer to a badge: counter, status, chip, tag, metadata, lozenge, pill, and bubble.
Last updated at: