Badge

A small status or count indicator. Attach it to any element as a floating pip, drop it inline next to text, or render it standalone — all three modes share the same class surface.

The examples are organized by layer: the class reference is the standalone @oriui/css layer, and the Framework API is the @oriui/vue component. Every example is live — flip its code between HTML (the standalone classes, also your htmx / Astro / Svelte / plain-HTML usage), Vue; HTML is the default.

Classes

A badge is a block class plus single-class token utilities — one class repoints one token; no base class is needed. The Vue props in Framework API map 1:1 to these. Two layout modifiers (ori-badge_dot, ori-badge_floating) and the wrapper class (ori-badge-anchor) complete the floating pattern.

Class	Type	Description
`ori-badge`	Block	Required base class. Defaults baked in: solid variant, primary color, full radius.
`ori-variant_*`	Style	solid · soft · outline · text · quiet
`ori-color_*`	Color	primary · secondary · success · warning · danger · info · surface · background
`ori-size-radius_*`	Radius	none · xs · sm · md · lg · xl · full
`ori-badge_dot`	Layout	collapses the badge to a small filled circle; content is hidden
`ori-badge_floating`	Layout	positions the badge in the top-end corner of its anchor wrapper
`ori-badge-anchor`	Wrapper	position:relative wrapper required for floating badges

À la carte: the classes above ship in @oriui/css/components/badge.css. .ori-badge-anchor lives in badge.css. Import a foundation (@oriui/css/base.css or @oriui/css/tokens.css) first — the token utilities (ori-color_*, ori-size-radius_*, …) live there, not in the component file. The full bundle @oriui/css is the default and already carries both; see à-la-carte imports.

Variants

Five visual styles, driven by the ori-variant_* single-class token.

SolidSoftOutlineTextQuiet

html

<span class="ori-badge">Solid</span>
<!-- swap the variant: ori-variant_soft / _outline / _text / _quiet -->
<span class="ori-badge ori-variant_soft">Soft</span>

Colors

All semantic roles. The badge inherits the shared ori-color_* token, so variant × color compose freely.

primarysecondarysuccesswarningdangerinfosurface

html

<span class="ori-badge ori-color_danger">danger</span>

Variant × color compose freely — e.g. a soft success badge or an outline danger badge:

ApprovedErrorBeta

html

<span class="ori-badge ori-variant_soft ori-color_success">Approved</span>
<span class="ori-badge ori-variant_outline ori-color_danger">Error</span>

Radius

From none (square) to the default full (pill).

nonesmmdlgfull

html

<span class="ori-badge ori-size-radius_none">none</span> <span class="ori-badge">full</span>

Count & max

Pass a number to content. Set max to cap the display value — any number exceeding max renders as {max}+.

54299+9

html

<span class="ori-badge">5</span>
<!-- cap manually in your template when not using Vue -->
<span class="ori-badge ori-color_danger">99+</span>

Dot

dot collapses the badge to a small filled circle. Content is hidden; it is always decorative (aria-hidden="true") unless you give it an aria-label.

html

<!-- dot is always aria-hidden unless it has an aria-label -->
<span class="ori-badge ori-badge_dot ori-color_danger" aria-hidden="true"></span>

Floating

The badge floats over wrapped content — floating needs the badge to wrap an anchor. In Vue, pass the anchor into the default slot and add the floating prop (without a default slot floating has nothing to position against and is ignored). In HTML, wrap the anchor in ori-badge-anchor and add ori-badge_floating to the badge itself.

399+

html

<!-- wrap anchor content in ori-badge-anchor, add ori-badge_floating to the badge -->
<span class="ori-badge-anchor">
    <button class="ori-button ori-variant_soft ori-color_primary ori-size-radius_full">Inbox</button>
    <span class="ori-badge ori-badge_floating ori-color_danger" aria-label="3 unread">3</span>
</span>

Common patterns

A notification bell, an avatar with a status pip, and a tab bar with unread counts.

399+

New

html

<!-- notification bell -->
<span class="ori-badge-anchor">
    <button class="ori-button …" aria-label="Notifications"><!-- bell icon --></button>
    <span class="ori-badge ori-badge_floating ori-color_danger" aria-label="12 unread notifications">12</span>
</span>

<!-- status dot on avatar -->
<span class="ori-badge-anchor">
    <div class="ori-avatar …"><!-- avatar --></div>
    <span class="ori-badge ori-badge_dot ori-badge_floating ori-color_success" aria-label="Online"></span>
</span>

<!-- inline tab counter -->
<span style="display: inline-flex; align-items: center; gap: 0.5rem">
    Messages
    <span class="ori-badge ori-variant_soft">5</span>
</span>

Accessibility

The accessibility contract holds across every layer — the standalone classes and the Vue component render the same attributes.

A badge with visible text content (content) conveys that text to assistive technology directly.
A pure dot badge — or an empty badge with no aria-label — is marked aria-hidden="true" because it carries no information for screen readers.
Supply an aria-label whenever the badge conveys meaning that a sighted user can read but a screen reader cannot (e.g. a dot meaning "online", or a floating count with no textual fallback nearby).
A floating count that visually annotates an already-labeled control (e.g. "Inbox (3 unread)") should carry aria-label on the badge element or be hidden with aria-hidden="true" if the parent label already includes the count.
The badge is a <span> — it has no interactive role and no keyboard contract of its own. When a badge and its anchor together form an interactive control, apply focus management and ARIA to the outer interactive element.

Attribute	Condition	Value
`aria-hidden="true"`	`dot` with no `aria-label`, or an empty badge with no `aria-label`	`"true"`
`aria-label`	`ariaLabel` is set	its value

Framework API

The props, events, and slots of the Vue component. The standalone CSS layer has no component API — its surface is the classes above.

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	—	Accessible name (`aria-label` in a template). Needed by a dot or a count that means something a sighted user reads off the screen.
`color`	`ThemeColor`	`'primary'`	Semantic color role: `primary` · `secondary` · `success` · `warning` · `danger` · `info` · `surface` · `background`.
`content`	`string \| number`	—	Text or number to display. Numbers are capped to `max+` when `max` is set.
`dot`	`boolean`	`false`	Collapses the badge to a small filled circle; content is hidden.
`floating`	`boolean`	`false`	Positions the badge in the top-end corner of the default-slot anchor (requires a default slot child).
`max`	`number`	—	When `content` is a number and exceeds `max`, the display value is capped to `{max}+`.
`radius`	`RadiusSize`	`'full'`	Corner radius: `none` · `xs` · `sm` · `md` · `lg` · `xl` · `full`.
`variant`	`Variant`	`'solid'`	Visual style: `solid` · `soft` · `outline` · `text` · `quiet`.

Events & attributes

OriBadge declares no custom events. It sets inheritAttrs: false and applies v-bind="$attrs" directly to the inner .ori-badge element — so id, class, data-*, and event listeners always land on the badge element regardless of whether a default slot (the anchor wrapper) is present.

Slots

Slot	Description
`default`	The element the badge floats over. When provided, the component wraps both the slot content and the badge in an `ori-badge-anchor` span. When absent, the badge renders standalone.
`content`	Custom badge content, replacing the capped `content` value (`{max}+`) that renders by default. Only renders when not a `dot`. A badge that uses this slot is kept in the a11y tree (not decorative).