Badge

Badges display additional metadata related to a resource they're nearby.

#Usage

#Pending

Pass isPending to render any variant with a dashed border, indicating a tentative or not-yet-finalized state. Combines with any variant.

#Progress

Pass progress to render a progress indicator in the left icon slot. The indicator replaces svgIcon or iconSrc while active and inherits the variant's text color.

Pass "indeterminate" to render a spinner when there's no numeric value to report.

Pass a number 0–100 for determinate progress.

progress and isPending are independent and can combine.

progress also works with shape="circle" without an icon.

#Subtle

Use the subtle variant to display information in a neutral tone. This is the default variant.

#Info

Use the info variant to draw attention, but not lean positive or negative.

#Success

Use the success variant to display information in a positive or successful tone.

#Warning

Use the warning variant to display information in an alerting tone.

#Error

Use the error variant to display negative or immediately concerning information.

#Upsell

Use the upsell variant to display information about billing plans or unlockable product features.

#Ghost

Use the ghost variant to convey that the badge is an uninitialized state.

#Long

Text gets cut off by ellipses when the badge text gets long.

#With a neighbor

Displays inline.

#Small

When a badge is small, it has a smaller font size and a height of 20px.

#Numbers

#Icons

Icons can be used in badges when additional clarity is required and the icon is highly relevant. Icons should not be used for decoration.

Icon colors can be overridden with the iconColor prop. Use this only when a different color is highly relevant.

Integration logos can be shown with the iconSrc prop.

#Circle

Use shape="circle" to render an icon-only circular badge. svgIcon or iconSrc must be provided, and children are not rendered.

#Rectangle

Use shape="rectangle" to render the badge as a rectangle shape instead of the default pill shape.

#As Button

If you are using a Badge as a button, use the BadgeButton component to pass through the appropriate HTML layout and accessibility features.

#Actions

Close buttons and other actions can be shown with the rightAction prop.

#Groups

Badge group is used to display multiple badges and collapse them to a single line, if necessary.

If truncated, use the same variant as size props on the BadgeGroup as it's children Badges. These styles will determine the appearance of the "more" button.

By default the badge group will render popover content in a portal. To disable this pass removePortal.

When badge group is not constrained by the parent container and has the ability to show all badges without truncation, pass truncate={false} to disable it.

#Guidelines

#When to use

• When displaying a category, status, or count chip near the resource it describes.

#When not to use

• If conveying live operational state rather than a category, use a status indicator instead.

#Placement

Always position a badge immediately after the resource they're related to.

#Content

Prefer one or two words max.

#Props

#Badge

Inherits margin props.

Name	Default	Description
variant	"subtle"	"subtle" | "info" | "success" | "warning" | "error" | "upsell" | "ghost" | "accent" Badge variant determines the purpose it is used for, and it's appearance.
size	"md"	"sm" | "md" | "lg" Determines the size of the badge.
isPending	false	boolean When `true`, renders the badge with a dashed border to indicate a tentative or not-yet-finalized state. Combines with any `variant`.
progress	—	number | "indeterminate" Renders a progress indicator in the left icon slot. Pass a number `0`–`100` for determinate progress, or `"indeterminate"` to render a spinner. Replaces `svgIcon`/`iconSrc` while active. Combines with `isPending` and any `variant`.
svgIcon	—	ComponentType<SVGAttributes<SVGElement>> Badge icon that's displayed on the left. Can be either a component or an object with props to override defaults.
iconSrc	—	string URL for an image icon.
iconColor	—	ColorProps["color"] Override the default icon color.
rightActionProps	—	IconButtonProps & Record<`data-${string}`, string> Right action configuration.
aria-label	—	string
shape	—	"rectangle" | "circle" Determines the shape of the badge. Use `"circle"` to render an icon-only circular badge (requires `svgIcon`, `iconSrc`, or `progress`).
children	—	ReactNode Badge text.

#BadgeGroup

Root-level component for displaying groups of badges.

All Badge components must be children of BadgeGroup.

Inherits margin props.

Name	Default	Description
truncate	true	boolean Display as much badges as possible on a single row and show the rest in a popover.
removePortal	false	boolean Determines if the popover content is rendered in a portal.
variant	"subtle"	BadgeProps["variant"] Determines the appearance of the "more" button, if applicable. Use the same variant as the group's children badges.
size	"md"	BadgeProps["size"] Determines the size of "more" button, if applicable. Use the same size as the group's children badges.
children	—	ReactNode Badges.