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 badgelet 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.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add badgeuse 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
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
| Prop | Type | Default | Description |
|---|---|---|---|
badgerequired | BadgeModel | — | Model. |
size | String | "sm" | `sm` · `md` · `lg`. |
icon | Option<String> | Default::default() | Leading icon, sized to the badge (12, 14 or 16 px). |
roll | bool | Default::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
| Key | Action |
|---|---|
| — | 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
| Transition | Duration | Easing | Notes |
|---|---|---|---|
| Label swap + width | 180 ms fade/blur, width spring.snap 214 ms | ease.out | Arc |
| Toggle chip fill | 120 ms | ease.out | |
| Toggle check grow | 214 ms | spring.snap | |
| Chip press | 80 ms, 0.97 | ease.out | |
| Entity card | 180 ms in, instant out | ease.out | |
| Count roll | 280 ms (dur.digit.roll) | ease.out | Oxyn plus |
| Reduced motion | halo off (static dot), swaps fade in 80 ms, no grow | linear |
Responsive behaviour
- Inline-sized: sits in table cells, list rows and headers; three sizes.
Edge cases (spec)
- Counts above
maxshow99+; 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
Badgefromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
BadgeElinoxyn_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.