Badge & pagination

Both components exist because a set is bigger than the screen. A badge says how many there are; pagination says which ones you are looking at. Both are answers to the same clinical question — what am I not seeing? — and both are dangerous when they answer it approximately.

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.

Pagination is the more consequential of the two, because it hides things. Its rule follows directly from Filter: a clinician must always be able to see the size of the whole set and know that something outside the current page needs attention.

Badge

• 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.

Pagination

Prefer not to paginate at all. Virtual scrolling with a fixed header keeps the set continuous and the total visible, and it does not create the class of error where a patient exists on page three. Paginate when the set is genuinely large, the order is stable, and a page boundary carries no clinical meaning.

States

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.
• Pagination is a <nav> with an aria-label, and each control is labelled by page — "Page 3", not "3".
• aria-current="page" on the active control, alongside fill and weight.
• The range line is a live region so changing page announces the new range and total.
• Focus after a page change moves to the top of the set's region, not to the next pagination button, so a keyboard user is not left below the content they requested.
• Targets ≥ 24 px with ≥ 24 px between centres (WCAG 2.2 SC 2.5.8). Page numbers are the control most often built at 18 px.
• Disabled previous/next stay in the tab order as aria-disabled with a reason, rather than vanishing and shifting the row under a travelling pointer.
• Reflow to 320 px — page numbers collapse to previous/next plus the range line, never to an icon-only pair (SC 1.4.10).

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. Mitigates: dilution of the IEC 60601-1-8 palette, and priority conveyed by a number nobody opens.
• Counts are exact and uncapped. Mitigates: a set's true size being unknowable at a glance.
• Zero rendered; unknown rendered differently. Mitigates: a failed count read as an absence of results.
• Range and total always shown. Mitigates: a page read as the whole record.
• Order stated alongside the range. Mitigates: items moving between pages under an order the clinician cannot see.
• Off-page urgent items reported above the set. Mitigates: an unacknowledged result on a page never visited.
• Alarm queues, acknowledgement lists and handover views are never paginated. Mitigates: a page boundary read as the end of the work.
• Position re-anchored when the set changes. Mitigates: acting on a row that moved beneath the page index.
• Previous page retained while loading. Mitigates: a blank region read as an empty set.

Implementation

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

// A badge takes a count and the thing being counted. There is no
// variant prop, because a badge has no clinical variants.
<Badge count={6} of="results" />
<Badge count={null} of="results" unavailableReason="Lab feed unreachable" />

// Enforced at the boundary: no alarm token may reach a badge.
if (props.className && /alarm-(critical|urgent|advisory)/.test(props.className)) {
  throw new Error("[Badge] alarm colours are reserved. Use StatusChip for priority.")
}

// Pagination requires the set size and the order, and computes what is
// unacknowledged outside the current page.
<Pagination
  page={1}
  pageSize={25}
  total={63}
  orderedBy="Newest first"
  offPage={{ urgent: 2, page: 3 }}
  prohibitedFor={["alarmQueue", "handover"]}   // dev-time guard
/>

Related

• Status chip — where clinical priority belongs instead.
• Filter — the same "what am I not seeing?" rule, applied to criteria.
• List & tree — counts on branches, and the denominator rule.
• Data grid — virtual scrolling, the preferred alternative to pagination.
• Colour — why alarm hues are reserved.
• Typography — tabular numerals in counts and page numbers.