HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
BadgeView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA count or a dot pinned to the corner of another element.StableSince 0.1.0MarkersUsageimport'@fusion.dev/helix/badge'import'@fusion.dev/helix-headless/badge'Preview
API ReferenceRoothelix-badgeA count or a dot pinned to the corner of another element.
PropTypeDescriptionattention"bounce"|"pulse"An effect that draws the eye to the mark: pulse swells it in a loop and
bounce hops it, as Web Awesome's badge does.emphasis"outlined"|"solid"|"subtle"How strongly the mark is drawn: solid, outlined or subtle, Tag's
axis.formatOptionsIntl.NumberFormatOptionsIntl.NumberFormat options a count is written with, such as
{"notation":"compact"} for 1.2K, written as JSON in the attribute.labelstringDefault""The badge's name, read by screen readers.localestringDefault""The locale a count is written in under format-options, and whose plural
rules label picks a form by, such as de.maxnumberThe largest number the badge shows.placement"bottom-end"|"bottom-start"|"inline"|"top-start"Where the mark sits: a corner, top-start, bottom-end or bottom-start,
or inline, in the line after the content.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"What the mark means. The stylesheet picks the fill from it.valuenumber|stringDefault""The count or short text to show.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element being decorated.iconAn icon inside the mark, before the count, or the whole mark when there is no value. Hidden from screen readers.
PartDescriptioniconThe slot the icon arrives through, inside the indicator. A slot draws no box, so it passes inherited properties, such as color, to the icon.indicatorThe count, or the dot when there is no value. Carries data-dot when there is no value, data-single when the count is one character, and data-blank when the value is zero.
CSS PropertyDescription--badge-attention-durationHow long one beat of attention takes.--badge-background-colorThe fill of the indicator.--badge-colorThe color of the count, to pair with a fill set through --badge-background-color.--badge-font-weightThe weight of the count.--badge-gapThe space between the content and the count under placement="inline".--badge-icon-sizeThe size of an icon in the icon slot. The count's own size by default.--badge-offsetPulls the mark in from the corner, along both axes.--badge-radiusHow far the indicator's corners are rounded.--badge-ring-colorThe color of the ring between the indicator and what is behind it.
Custom stateDescriptionblankThe value is zero, so there is no mark.cappedThe count is past max, so the mark shows {max}+.dotThere is no value and no icon, so the mark is a dot.has-iconSomething is slotted into icon, so it is drawn inside the mark.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-badgeA count or a dot pinned to the corner of another element.
PropTypeDescriptionformatOptionsIntl.NumberFormatOptionsIntl.NumberFormat options a count is written with, such as
{"notation":"compact"} for 1.2K, written as JSON in the attribute.labelstringDefault""The badge's name, read by screen readers.localestringDefault""The locale a count is written in under format-options, and whose plural
rules label picks a form by, such as de.maxnumberThe largest number the badge shows.valuenumber|stringDefault""The count or short text to show.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element being decorated.iconAn icon inside the mark, before the count, or the whole mark when there is no value. Hidden from screen readers.
PartDescriptioniconThe slot the icon arrives through, inside the indicator. A slot draws no box, so it passes inherited properties, such as color, to the icon.indicatorThe count, or the dot when there is no value. Carries data-dot when there is no value, data-single when the count is one character, and data-blank when the value is zero.
Custom stateDescriptionblankThe value is zero, so there is no mark.cappedThe count is past max, so the mark shows {max}+.dotThere is no value and no icon, so the mark is a dot.has-iconSomething is slotted into icon, so it is drawn inside the mark.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCappedA count past its maximum, shown as the maximum and a plus sign.DotA dot with no number, to show that something is unread.EmphasisA count drawn solid, outlined and subtle with emphasis, and a label that counts with {count}.IconAn icon inside the mark, alone on an avatar and before a count on a button.InlineA count placed inline inside a button, read as part of the button's name.On ButtonsA count on three buttons, in the default, neutral, and danger tones, with each count in its button's name.PreviewA count over the thing it counts.PreviewA count over the thing it counts.TonesA count in each tone, the same tones a tag uses.