Filter

Filtering is the only component in this system whose entire job is to hide clinical information. That makes it the one that most needs to be honest: what is hidden, how much of it, and how to get it back — visible at all times, in one glance, without opening anything.

Overview

A clinician who forgets a filter is on is looking at a subset of a patient's record while believing they are looking at the record. Every rule here follows from that single failure: filters are loud, counted and reversible.

The system's default position is that filters are a convenience for large sets, not a workflow. They never persist silently, never survive a patient change, and never apply to anything at advisory priority or above.

Anatomy

What a filter may never hide

• Not filterable: unacknowledged critical, urgent and advisory alarms; a patient's identity band; any item the clinician has explicitly flagged.
• Filterable: resolved and acknowledged items, informational status, ward and team scoping, time windows, result types.
• Never filter to zero without saying why. An empty filtered set names the filters responsible and offers to remove them — see Empty state.
• Never filter across a patient boundary. Filters are cleared on patient change and never restored from a previous patient's session.

Persistence

A filter that outlives the clinician's memory of setting it is the hazard. So persistence is deliberately weak, and always announced.

How the criteria combine

Three tags reading Ward: Emergency, Awaiting review and Arrived after 12:00 describe a set. They do not say which set. Is it patients matching all three, or patients matching any of them? The two answers differ by a factor of several, and the count line cannot tell them apart — 4 of 19 is equally consistent with both.

The convention this system uses, and states rather than assumes:

• Several values within one dimension are any. Ward: Emergency or Cardiology. Choosing a second ward widens the set, which is what a clinician selecting two wards expects.
• Different dimensions are all. Ward and status and arrival time each narrow further. Adding a dimension always shrinks the set.
• Both are stated on screen — "Emergency or Cardiology · awaiting review · arrived after 12:00" reads as a sentence and disambiguates itself. Tags in a row do not.

The failure this prevents is quiet and one-directional. A clinician who believes the criteria are any when they are all thinks they are looking at a wider set than they are — which is precisely the belief this component exists to stop them holding.

A filter someone else chose

Filter state belongs in the URL, for the same reasons as Pagination: back and refresh behave, and a view can be sent to a colleague. That second reason introduces the one case this component is not otherwise designed for.

• The same applies to a saved or default view. A deployment that ships a pre-filtered worklist has made the same choice on the clinician's behalf, and owes the same statement.
• Filters never survive a change of patient or a change of shift, per Persistence. A URL is a way of sharing a view, not a way of smuggling one past that rule.
• A link that no longer resolves to the same set says so. Criteria referring to something that has since changed — a ward that closed, a clinician who left — are reported rather than dropped silently, because a filter that quietly stopped applying is a filter the reader still believes is on.

Filter or search

They look similar and answer different questions, and the difference matters most when neither returns anything.

Because they differ, so do their empty states. A filter with no matches says which criteria excluded everything and offers to remove them. A search with no results says what was searched and over what, per Empty state. Neither is an error, and neither is ever rendered as one — a red field on a filter that simply matched nothing tells the clinician they did something wrong when they did not.

The control and its tags

• Never an icon-only filter control. Offered widely for constrained space, and it fails here twice — this system has no icon set, and a filter is the one control whose purpose a reader must be able to name before pressing it. If the space is that tight, the screen has a layout problem rather than a labelling opportunity.
• Tags never truncate. The usual advice is to clip a long tag and put the full text in a tooltip; a tag reading Ward: Emerg… is a criterion the reader cannot verify, on a touch surface where the tooltip does not exist. Tags wrap onto further rows, which is what the rows are for.
• Tags are not reorderable. Their order carries no meaning, so dragging them achieves nothing and costs a single-pointer alternative under SC 2.5.7.
• Options are ordered by likelihood, then alphabetically past a dozen entries. A list a clinician has to read end-to-end every time is a list that gets guessed at.
• The count is announced when it changes, politely, as one summary — the number is the whole point of the component and a sighted reader gets it for free.

States

What the component enforces, and what it only asks for

A filter bar reports what is being hidden. It does not do the hiding, and the rules about what a filter may not conceal are enforced upstream of it.

Do's and don'ts

Accessibility

• The tag row is a labelled list — role="list" with aria-label="Active filters" — so the whole filter state can be read as a set, with its size announced.
• Each remove control names its filter in full: "Remove filter Ward: Emergency". A row of buttons all called "Remove" is unusable non-visually.
• The count line is a live region (aria-live="polite") so applying a filter announces the new denominator rather than silently changing it.
• Clear-all carries its count in the accessible name — "Clear all 3 filters".
• Focus after removal moves to the next tag, or to Add filter when the last one goes. It never falls to the document body.
• Tags are never colour-coded by dimension alone; the dimension is in the text.
• Never brand coral, never an alarm hue on a filter tag. Filtering is not a clinical state — see Colour.
• Targets ≥ 24 px including the remove control inside the tag, with ≥ 24 px between adjacent remove controls (WCAG 2.2 SC 2.5.8).
• Tags wrap, never scroll horizontally. A filter you have to scroll to see is a filter you do not know about (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's belief about what they are looking at matches what they are looking at. This is the whole purpose of the component.
• Efficiency — a large set narrowed in one action, and restored in one action. Neither direction should cost a mental model.
• Satisfaction — no residual doubt about whether something is hidden, which is the doubt that sends clinicians to a second system to check.

Clinical safety notes

• Active filters always rendered as readable tags. (the component) Mitigates: a filtered view mistaken for the complete record.
• Hidden quantity stated numerically at all times. (the component) Mitigates: the size of what is missing being unknowable.
• Alarms at advisory priority and above are unfilterable. (you) Mitigates: a deteriorating patient hidden by a scoping choice made minutes earlier.
• Filters cleared on patient change. (you) Mitigates: one patient's view constraints applied to another patient's record.
• Filters never restored silently at sign-in. (you; the component marks an inherited set as inherited) Mitigates: a shift beginning inside a narrowed view nobody set today.
• Previous set retained while applying. (you) Mitigates: a blank region read as an absence of patients.
• Zero-result state names the responsible filters. (you) Mitigates: an over-narrow filter read as "nothing to do".
• Criteria written in clinical language. (you) Mitigates: a filter misread under time pressure and left on.

Implementation

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

<FilterBar
  active={filters}               // each tag carries its own id and label
  onRemove={remove}
  onClearAll={clearAll}
  hiddenCount={15}               // required: how many rows the filter is hiding
  alarmsHeldVisible={2}          // shown despite the filter, and said so
  inherited                      // this filter came from a link, not from you
/>

// 'hiddenCount' is required, so a filtered view cannot be rendered without
// stating the size of what it is not showing.

What the component takes. This table used to list filters, total, escaped, subjectId, savedViewName — props the component does not have, and never had. Found by the registry gate’s props-table rule.

Related

• Affordance & perceivability — the general rule this page applies: a control exists only if every reader who can operate it can perceive it.
• Data grid — the primary consumer, and its column filters.
• List — the same denominator rule at a smaller scale.
• Search — narrowing by query rather than by criterion.
• Empty state — what a filtered-to-zero set must say.
• Triage worklist — why handover is never filtered.
• Tokens & governance — why the escape rule has no override.