Badge

A count, and nothing else. The rules that matter are not about rendering the number — they are about the number being exact, and about the set it is exact about, which is where badges actually mislead.

Overview

A badge is a count and nothing else. It never carries clinical state, never replaces a Status chip, and never becomes an alarm by turning red. A count of three tells you there are three things; it does not tell you any of them is critical, and it must not pretend to.

Every rule below is about the number being exact, or about the set it is exact about. The second is the harder one and the one this component gets wrong most often — see What the count counts. Where a set is larger than the screen, Pagination says which part of it you are looking at.

Anatomy, and the rule that carries the risk

• Exact, never capped. "99+" hides an order of magnitude. If the number is too wide for the space, the space is wrong.
• Zero renders. A hidden zero is indistinguishable from an unloaded count, which is the ambiguity Key–value pair exists to prevent.
• Unknown is not zero. A count that failed to load renders as — with a reason, never as 0.
• Never the only carrier of meaning. A badge always sits beside a label naming what is being counted.
• Never a dot alone for anything clinical. A dot says "something changed" and nothing else; it is permitted only for non-clinical notifications.
• Never on a disabled or unavailable control — a count on something you cannot open is a dead end.

What the count counts

Every rule above is about the number being exact. None of them is about the number being exact about what, which is where badges actually mislead. A badge is a claim with a hidden subject, and three things quietly change that subject.

A filter is active

The second badge is not wrong about anything it says. It is wrong about what it is about, and a clinician who set that filter twenty minutes ago has no way to tell. This is Filter's hidden-count rule arriving at a component that was designed without it in mind.

The reader cannot reach all of them

A count of forty results where the reader's role permits opening thirty-one is a count of things some of which do not exist for them. It reads as work they have not done. Either the badge counts what they can reach and says so, or it counts everything and states the difference — but the difference is stated, because Acting for someone else turns on a reader knowing what is being withheld and why.

A time window is implied

"6" beside Laboratory means six today, or six this admission, or six ever. The label carries the window or the badge does. Unscoped counts are read against whatever window the reader already had in mind, which is rarely the one the query used.

A count is a snapshot

A badge is only as current as its last fetch, and unlike a value in a Key–value pair it carries no timestamp of its own. On a worklist that polls every few minutes, a badge is a claim about the past presented in the present tense.

• Where the count drives a decision, its age is available. Not necessarily rendered beside every badge — that would be unreadable — but reachable, and rendered once for the surface as a whole: "counts as of 14:26:38".
• A failed refresh does not freeze a confident number. The count keeps its last value and the surface states that refreshing failed, per Pending value. A number that stopped updating and does not say so is worse than one that admits it.
• A count that has never loaded is not zero. Already the rule above; it is restated here because a polling failure at startup is the case that produces it.
• Do not animate the change. A count that ticks or flashes when it increments spends the movement budget that alarms depend on — see Motion. It updates, politely announced, and that is all.

Rendering the number

• Tabular figures, so a column of counts can be scanned for an outlier rather than read one at a time — see Typography.
• Group digits by locale, and never by hand. A thousands separator is a decimal point in several of the places this system claims to support, and a count is one of the few numbers where that ambiguity is survivable — which is exactly why it gets fixed here rather than argued about later.
• The accessible name is a sentence, and it agrees. "1 result", not "1 results"; the plural rules come from the platform's formatting, not from appending an s.
• The badge is never the target. It is content inside a row or a label, and the row is what is pressed. A 24 px badge made clickable is a control below the floor, sitting next to the larger control it will be mistaken for.

States

What the component enforces, and what it only asks for

A badge is a number and a noun, and the type holds both. What it cannot hold is whether the number is right, which is the whole of what a badge is for.

Do's and don'ts

Accessibility

• A badge is never a bare number. Its accessible name includes what is counted — "Laboratory, 6 results" — because "6" announced alone is meaningless.
• Badges that change are announced politely (aria-live="polite") or not at all. Never assertive: a count is not an interruption.
• Never colour alone. Badge styling carries no meaning, so there is nothing for colour to fail to convey — which is the point.

Outcomes of use

What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.

• Effectiveness — the clinician knows the true size of the set and is told about anything urgent they cannot currently see.
• Efficiency — a count answers "is it worth opening?" without opening anything, which is most of what counts are for.
• Satisfaction — exact numbers. A capped or approximate count is the kind of small dishonesty that makes people stop believing the rest of the screen.

Clinical safety notes

• Badges never take an alarm hue. (the component) Mitigates: dilution of the IEC 60601-1-8 palette, and priority conveyed by a number nobody opens.
• Counts are exact and uncapped. (the component) Mitigates: a set's true size being unknowable at a glance.
• Zero rendered; unknown rendered differently. (you) Mitigates: a failed count read as an absence of results.
• The count is over the whole set, or states what narrows it. (you; the component names what it counts) Mitigates: a number that is exact about a set the reader did not have in mind.
• A stale count says so. (you) Mitigates: a frozen number presented in the present tense after a failed refresh.
• The badge is never the target. (the component) Mitigates: a control below the size floor beside the larger one it will be mistaken for.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/badge.json

// A count and the thing being counted. No variant prop, because a badge
// has no clinical variants — and no max, so "99+" cannot be produced.
<Badge count={6} label="results" />

// A filter is narrowing the set: count stays the whole-set total.
<Badge count={40} label="results" hiddenByFilter={34} />

// Both plural forms, so the announced name agrees.
<Badge count={1} label={{ one: "result", other: "results" }} />

Related

• Pagination — which part of the counted set you are looking at.
• Status chip — where clinical priority belongs instead.
• Filter — the same "what am I not seeing?" rule, applied to criteria.
• List — counts on branches, and the denominator rule.
• Colour — why alarm hues are reserved.
• Typography — tabular numerals in counts.