Badge
Overlay badge for notification counts, status dots and labels, anchored to a wrapped element.
Preview
Rendering the live preview…
countRendering the live preview…
dotRendering the live preview…
maxRendering the live preview…
floatingStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-badge> — 3 parts: root ①, relative wrapper ②, and the absolute-positioned badge pill ③.- 1.origam-badge
- Root element (
display: inline-flex). Receives thetagprop (default<div>). Modifiers:--dot,--floating,--inline. - 2.origam-badge__wrapper
- Relative-positioned container that anchors the badge pill. Contains the
#defaultslot (the host element). - 3.origam-badge__badge
- The visible badge pill (
position: absolute). Location computed byuseLocation. Content capped atmax. Wrapped inOrigamTransitionfor show/hide animation. Hasrole="status",aria-live="polite",aria-atomic="true".
API
Props
All props accepted by this component, with their type, default value and description.
- contentnumber | string
- Text or number displayed inside the badge. Use max to cap large numbers.
- dotbooleanfalse
- Renders as a small dot without content — useful for status indicators.
- floatingbooleanfalse
- Floats the badge at the corner of the wrapped element with reduced offset.
- inlinebooleanfalse
- Renders the badge inline instead of as a positioned overlay.
- labelstring'origam.badge'
- Accessible aria-label for the badge element.
- maxnumber | string
- Maximum value to display. When content exceeds max, renders "max+" instead.
- modelValuebooleantrue
- Controls the badge visibility. Use v-model to bind two-way.
- offsetXnumber | string
- Horizontal offset from the anchor corner (CSS length or number in px).
- offsetYnumber | string
- Vertical offset from the anchor corner (CSS length or number in px).
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring'div'
- HTML element rendered at the root wrapper.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a 2px border ring around the badge (useful for contrast against the background).
- borderTopboolean | number | string
- disabledbooleanfalse
- Hides the badge overlay when true.
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- color
- Intent or custom foreground color applied to the badge.
- bgColor
- Badge background color.
- locationTAnchor'top end'
- Corner of the host element where the badge is anchored.
- Border-radius token for the badge pill. Default is {radius.full}.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- transitionboolean | string | TTransitionPropsOrigamFade
- Transition applied when the badge appears/disappears. Defaults to fade.
- statusTStatus
- statusIconPositionTStatusPosition
- iconTIcon
- hoverboolean | IStateEffectConfig
- hoverClassstring
- elevationTElevation
- Box-shadow elevation token for the badge.
- fontSizeTFontSize
- fontWeightTFontWeight
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
API
Slots
Content slots exposed by this component.
- #default
- The element the badge is anchored to. Wrapped in a relative-positioned container.
- #badge
- Custom content rendered inside the badge pill, replacing the content prop.
- #prepend
- Icon or content before the badge text.
- #append
- Icon or content after the badge text.
API
Emits
Events emitted by this component.
- @click:appendMouseEvent
- @click:prependMouseEvent
- @update:hoverboolean
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child component.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed badgeContentStyles.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Badge pill background. Overridden by color/bgColor prop and status.
- Badge pill foreground color.
- Pill border radius. Default is full circle; overridden by rounded prop.
- Badge pill height. Fixed at 20px (1.25rem). Shrinks to 9px in dot mode.
- Minimum badge width for circular single-digit display.
- Badge content font size.
- Badge content font weight.
- Transition duration for badge position/opacity animations.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Notes
- The badge pill has role="status" with aria-live="polite" and aria-atomic="true". Screen readers announce badge content changes (e.g. new count).
- The label prop (or the translated "origam.badge" key) is used as aria-label to describe the badge to screen readers. Pass a meaningful value like "5 unread notifications".
- In dot mode, the content is visually hidden (text-indent: -9999px) but the aria-label still conveys the status to screen readers.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- colorvar(--origam-color__action--primary---bg)
- Default badge pill background.
- dimensionvar(--origam-radius---full)
- Full-circle border radius by default.
- dimension1.25rem
- Badge pill height (20px).
- dimensionvar(--origam-font__size---sm)
- Badge content font size.
- colorvar(--origam-color__feedback--danger---bg)
- Background for error/danger status badges.
- duration225ms
- Badge position/opacity transition duration.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Count badges
Locations
Inline badge