Skip to content

Badge

A small status label that carries the colour: six tones plus four agent-state tones, soft, outline, solid or mono, a dot, a live dot that pulses and a count up to 99+.

oxyn add badge
MCP
Dioxus
let mut badge = BadgeModel::new("Running", Tone::Working);
badge.live = true; // pulses every 1.8 s

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Rendered from Rust at build time · goes live when visible

When to use

  • Small labels that carry meaning at a glance: a run's status, an unread count, a model's version, a filter, a number inside a sentence ("restock in 7 days"), a company or person the agent is talking about.
  • These are the only chrome pieces allowed to carry colour, and only when the colour *is* the meaning (status, agent identity, monogram).

When not to use

  • A dot and a label for any of the 13 agent states, as a pill, inline or a dot alone: use Status indicator instead.
  • Initials on a colour of their own, a pixel mark for agents with a ring that follows the agent state, presence, a model badge, a progress ring and an overlapping group with +N: use Avatar instead.
  • Numbers that roll digit by digit like an odometer, or count up through the values in between: use Number Ticker instead.

Installation

Badge is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.

Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add badge
Rust
use crate::oxyn::{Badge, PRIMITIVES_CSS};

Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{Badge, PRIMITIVES_CSS};

Usage

Dioxus · rust
let mut badge = BadgeModel::new("Running", Tone::Working);
badge.live = true; // pulses every 1.8 s

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Examples

Live

Pulses while something runs.

Code
let mut badge = BadgeModel::new("Running", Tone::Working);
badge.live = true; // pulses every 1.8 s

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Roll lg

Large, the label rolls as the status changes.

Code
let mut badge = BadgeModel::new("Running", Tone::Working);
badge.dot = true;

rsx! {
    Badge {
        badge: badge,
        size: "lg",
        roll: true // a new label rises in,
    }
}

Dot success

Leading dot.

Code
let mut badge = BadgeModel::new("Passed", Tone::Success);
badge.dot = true;

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Outline warning

Border only.

Code
let mut badge = BadgeModel::new("Needs review", Tone::Warning);
badge.fill = Fill::Outline;

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Count

Round count, 99+.

Code
let mut badge = BadgeModel::new("unread", Tone::Neutral);
badge.fill = Fill::Solid;
badge.count = Some(128); // shows 99+

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

Mono

Monospace tag, no fill.

Code
let mut badge = BadgeModel::new("v0.4.2", Tone::Neutral);
badge.fill = Fill::Mono;

rsx! {
    Badge {
        badge: badge,
        size: "md",
    }
}

API reference

Badge

PropTypeDefaultDescription
badgerequiredBadgeModel—Model.
sizeString"sm"`sm` · `md` · `lg`.
iconOption<String>Default::default()Leading icon, sized to the badge (12, 14 or 16 px).
rollboolDefault::default()Roll the label: a changed label rises in with a short blur (keyed on the text).

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
—Not focusable; it labels the thing next to it

Accessibility

  • Status is never colour alone: every tone carries its text label.
  • The live dot is decorative and stops under reduced motion.
  • Counts over 99 are read as "More than 99 unread"; live badges add "(in progress)".
From the spec

Colour is never the only signal: badges carry words, live badges add "(in progress)", deltas speak "up / down". Toggle chips use aria-pressed; removable chips are a focusable group whose × button is named "Remove {label}". The entity card is linked with aria-describedby and closes on Esc. Tone foregrounds meet 4.5:1 on their soft backgrounds in both themes.

Motion & interaction

  • Live dot: a soft halo grows out of the dot (scale 1 → 2.6) and fades every 1.8 s — nothing Else moves.
  • Label change (Arc): the new label rises in from a short blur while the pill width springs. Passive reflows (font swap) resize instantly.
  • Toggle chip: the check grows in from zero width (spring.snap), the label slides over, the fill inverts in 120 ms; press 0.97.
  • Entity card: fades and lifts 5 px in 180 ms; leaves at once.
  • Count roll (Oxyn plus) uses the number ticker's digit roll when a count changes.
Timing
TransitionDurationEasingNotes
Label swap + width180 ms fade/blur, width spring.snap 214 msease.outArc
Toggle chip fill120 msease.out
Toggle check grow214 msspring.snap
Chip press80 ms, 0.97ease.out
Entity card180 ms in, instant outease.out
Count roll280 ms (dur.digit.roll)ease.outOxyn plus
Reduced motionhalo off (static dot), swaps fade in 80 ms, no growlinear

Responsive behaviour

  • Inline-sized: sits in table cells, list rows and headers; three sizes.
Edge cases (spec)
  • Counts above max show 99+; zero counts still render (badges are explicit), unlike the reaction bar's hide-zero rule.
  • Long chip labels truncate with an ellipsis at the host's max width; the full text is the name.
  • Names with one word → one initial; punctuation and emoji are skipped (initials("Jean-Luc Picard") = "JP"; empty = "?").
  • The same name always gets the same monogram colour (seed_index, case- and space-insensitive).
  • Inline pills sit on the text baseline (vertical-align: middle) and never change line height.
  • High contrast theme: soft fills gain a 1 px border through the tokens.

Notes for AI

  • Import Badge from oxyn_dioxus and include PRIMITIVES_CSS plus the token stylesheet once.
  • A GPUI version exists: BadgeEl in oxyn_gpui.
  • Props to set first: badge.
  • It reads a clock (now) for live timers; pass one clock for the whole page rather than one per component.
  • Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI