variant is visual emphasis only. Use destructive for failures and blocking problems, success and warning for healthy and degraded states, secondary or outline for neutral metadata, and the default for the one thing you want noticed.
Icons and progress
With marks
Default density
Compact density
Restart from the initial state
Show the copyable source
The default slot takes text plus inline marks such as an icon or a Spinner. Keep them decorative, with aria-hidden or label="", when the text already says what they mean.
Badge does not announce changes; put a badge whose state matters to assistive technology in a live region the application owns.
Content follows dir, and long labels can wrap within the available width. Prefer short labels; there is no automatic truncation or tooltip.
In context
Status in a list
Default density
Compact density
Restart from the initial state
Show the copyable source
Write counts with their noun, like “12 unread”, rather than a bare number. A Badge inside a Button or link stays passive, so the composition keeps one interactive target.
Counts in buttons
Default density
Compact density
Restart from the initial state
Show the copyable source
interactive declares that a badge acts, and partContracts supplies the native element that does: a button for filter chips, an a for a link. Keep bind on that element and render content inside it. The pill keeps its size while its pointer target grows to the minimum, so leave room between interactive badges. The link variant alone never navigates. For a full action, form or loading behavior, use Button.
Native buttons retain Enter/Space activation, anchors retain navigation and modifier-click behavior, and the delegate owns their disabled policy. Use native semantic hosts; an arbitrary focusable div is not an equivalent action. Do not nest other interactive controls inside an interactive badge. Native click bubbles through the shadow boundary; prevent its default when the application needs to cancel navigation.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptionvariantvariant'default' | 'secondary' | 'destructive' | 'success' | 'warning' | 'outline' | 'ghost' | 'link''default'Visual emphasis only: destructive, success and warning are the status pills, outline and secondary neutral metadata.interactiveinteractivebooleanfalseDeclares that the badge acts; the badge part contract supplies the native button or link that does.
Slots
SlotDescriptiondefaultThe label: text, with an Icon or a Spinner as a decorative mark.
CSS parts
PartDescription::part(badge)The pill: the host of the label and of the variant appearance.
Related
Components, widgets and patterns that use this one.