Skip to content
omaris

Communication

Badge

Badge — a status pill, or the count that rides on an icon.

import { Badge } from 'omaris'
Learn

Examples

Status and counts

A status pill on a row, or a count on its own. max caps it — 100 becomes 99+, because past that the number stops mattering.

Live Building Failed 7 99+ 128
<script lang="ts">	import { Badge } from 'omaris';</script>​<Badge tone="success" variant="tonal">Live</Badge><Badge tone="warning" variant="tonal">Building</Badge><Badge tone="destructive" variant="tonal">Failed</Badge><Badge value={7} /><Badge value={128} /><Badge value={128} max={999} />

Anchored

anchor pins it to the corner of a relative parent — unread on a bell; dot drops the number when "something is new" is all that matters.

Something new
<script lang="ts">	import { Badge, IconButton } from 'omaris';</script>​{#snippet bell()}	...{/snippet}​<span class="relative inline-flex">	<IconButton aria-label="Notifications">{@render bell()}</IconButton>	<Badge anchor="top-end" value={4} tone="destructive" label="4 unread" /></span>​<span class="relative inline-flex">	<IconButton aria-label="Notifications">{@render bell()}</IconButton>	<Badge anchor="top-end" dot tone="success" label="Something new" /></span>

When to use it

Use it for

  • A count on an icon: unread on a bell, items in a cart. value with anchor="top-end" on a relative parent, and max so 100 reads "99+".
  • "Something new" with no number. dot on a Navigation Bar item or an Icon Button.
  • A read-only status on a row or a card: "Paid", "Draft", "Beta". A labelled pill, tonal or outlined, with tone carrying the meaning.
  • A coloured word in a table cell. variant="text" when a pill in every row is too loud.

Not for

  • Anything pressable, like a filter or a removable tag → Chip. A badge has no state layer and no focus ring.
  • A sentence → Alert.
  • A number people compare across rows → Text with tabular-nums, or a Gauge.
  • A message that should be noticed now → Toast. A badge waits to be seen.

Do

  • Give a count or a dot a label: "3 unread", not "3", so a screen reader says what the number is.
  • Put relative on the parent before you anchor. The badge is positioned absolutely and needs a box to pin to.
  • Keep one tone per meaning across the app: success paid, warning pending, destructive failed.
  • Clear the dot as soon as the thing has been seen. A dot that never goes away means nothing.

Don't

  • Use filled for status pills in a table. A column of solid capsules fights the data; use tonal or outlined.
  • Show a zero. No value, no badge.
  • Anchor a count to something nobody will act on. "99+" on a log tab is noise.
Pairs with Icon Button Navigation Bar Avatar Table Chip

Quick reference

tone
  • primary (default)
  • secondary
  • tertiary
  • destructive
  • success
  • warning
  • info
variant
  • filled (default)
  • tonal
  • outlined
  • text
size
  • sm
  • md (default)
  • lg
anchor
  • none (default)
  • top-end
  • top-start

Pins the badge to the corner of a relative parent — a sibling of what it counts, not a wrapper around it. Without a positioned ancestor the badge's containing block is the page, and it lands in the top corner of the screen rather than of the bell.

API

Badge

Badge — a status pill, or the count that rides on an icon.

Same two axes as the button: variant is the fill style and tone the color role, resolved through the shared --btn-* properties. dot and count are MD3's small and large notification badges; both take anchor to pin themselves to the corner of a relative parent.

import { Badge } from 'omaris'

Props

variant

Defaults to 'filled'

BadgeVariant
filled
tonal
outlined
text
Ghosted — the label carries the color, nothing else.
tone

Defaults to 'primary'

BadgeTone
primary
secondary
tertiary
destructive
success
warning
info
size

Defaults to 'md'

BadgeSize
sm
md
lg
dot

Defaults to false

boolean

Renders the 6dp dot instead of a label.

value
number

A number badge. Values above max render as "99+", and the pill stays a circle until two digits force it wider.

The number is the content: a badge given a value draws it and nothing else, so anything passed as children is dropped. Put the thing being counted beside the badge, inside a relative box.

max

Defaults to 99

number

Cap for value.

anchor

Defaults to 'none'

BadgeAnchor

Corner of the relative parent to pin to.

none
top-end
top-start
label
string

Screen-reader text — "3 unread", not "3".

class
string
children
Snippet