Data grid

The substrate under every list of patients, results and events. Its defaults decide what a clinician sees first and what they never see at all, which makes sorting, filtering and row insertion safety behaviours rather than conveniences.

Overview

A general-purpose data grid optimises for flexibility: sort anything, filter anything, hide anything, remember what the user did last time. Every one of those defaults is wrong in a clinical queue, because each of them can silently remove a patient from view.

This component keeps the flexibility and inverts the defaults. Everything is available; almost nothing is on by default; anything currently hiding data says so on screen.

Anatomy

Sorting

The default sort is a product decision with clinical consequence, declared once and enforced by the component. In AcuteLine it is priority, then longest waiting — see Triage worklist.

• Default sort is restored on every session start. A sort order inherited from the previous shift is a hazard, so it is never persisted.
• A non-default sort is stated in the bar, in words, persistently — a clinician walking up to a colleague's screen must be able to see the queue is not in priority order.
• One-click reset is always present while a non-default sort is active.
• Sorting never reorders rows under the pointer. It is an explicit action, so the reorder is expected — but focus stays on the header that was activated.

Live data

Once inserted, new rows carry a temporary marker so a clinician can see what changed since they last looked. The marker is positional and textual, never a colour wash that could be mistaken for priority.

Filtering and columns

• No filter is active on open. Filters are never persisted across sessions.
• Hidden row count is always shown next to the filter control — Showing 5 of 23 · 18 hidden by filter.
• Critical rows bypass filters entirely and render with a note that they fall outside the current filter.
• Hidden columns are disclosed in the state bar. A column a clinician does not know is missing is worse than one they chose to hide.
• Export and print always contain every row in scope, filtered or not, with the filter stated on the output.

Density

Density never removes information — it reduces padding only. A compact grid that drops the MRN is not compact, it is incomplete. On touch platforms use comfortable, and the row must satisfy the physical touch floor — the component cannot tell a touch surface from a workstation, so this is yours; see Scaling.

Inside a cell

Density above governs how much padding a row has. This governs what happens when the content still does not fit, which is the more consequential question.

The common answer is to truncate and put the full text in a tooltip. It fails here for the reason it fails on Navigation and Accordion: hover does not exist on a touch cart, so the value simply is not there — and in a grid the thing being hidden is a name, an identifier or a result rather than a section label. Tooltip already forbids a tooltip carrying anything load-bearing; a truncated cell makes the tooltip the only copy.

Zebra rows

Alternating row fills help the eye track across a wide grid, and they are permitted. What they cost is contrast headroom: every foreground in the grid now has two backgrounds to clear rather than one, and the striped row is the one that gets forgotten. Check both, in both themes — the checklist greyscale pass is the place. Where the grid already carries a priority rail and status chips, dividers are the safer choice.

Editing in place

A form control inside a row is convenient and is the wrong place for a value with a clinical envelope. A dose stepper in a 36 px row is a control that can be nudged by a stray scroll, beside eleven identical ones, with no room for the units, the permitted range or the confirmation that Numeric input requires.

• Anything with a clinical envelope is edited where the envelope fits — a panel or a dialog that can show units, range and what the change replaces.
• Inline editing is for fields with no envelope: a free-text note, a flag, an assignment. Even then the cell is a real labelled control, not a div that becomes editable on a click nobody advertised.
• An editable cell is visibly editable before it is touched. A control that appears on hover is a control that does not exist on touch and is invisible to a keyboard user until focus lands in it.

What may be done to a row or a column

Grids accumulate interactions — reorder, resize, freeze, hide, pin, launch. Each is reasonable and most arrive with an affordance that only some users can perceive.

The pattern underneath: an interaction is available when its affordance is visible to everyone who can use the grid. Hover-revealed controls, drag-only reordering, modifier-key combinations and double-click all fail that in the same way, and they fail it silently — every one of them works perfectly for the person who built it.

Virtual scrolling, and the count that must stay true

Pagination prefers virtual scrolling because the set stays continuous and its size stays on screen. That preference comes with an obligation most implementations miss.

• No tab stop per cell. This is a <table>, not the ARIA grid widget: its cells are not focusable, and a screen reader’s own table commands move between them. This line used to promise arrow-key cell navigation the component has never had. Controls you put in cells are tab stops each; if a row carries several, a grid widget with its own keyboard model is yours to build.
• The rendered window never changes what is true. Counts, the state bar and any off-screen alarm report describe the whole set, never the rows currently mounted.
• Scroll position survives leaving and returning, per Pagination. Re-reading a queue to find your place is where the second-to-last row gets skipped.
• Loading more on scroll is never the only route to the end. The total is stated from the start, so a clinician always knows how much there is — the objection infinite scroll earns.
• New rows arriving are staged, not spliced — see Live data. Virtualisation makes insertion cheap, which is exactly why it needs the same restraint.

Empty, loading and degraded

• Loading shows skeleton rows, never a blank grid, so the clinician knows data is coming rather than absent.
• A partial load is an error, not a shorter list. If some rows failed to fetch, the grid says so at Urgent — silent partial coverage is the most dangerous state a clinical queue can be in.
• Stale data is labelled with its age once beyond a documented threshold.

What the component enforces, and what it only asks for

Almost everything this page argues about sorting, staging and selection is behaviour the grid does not own. It renders rows you give it, in the order you give them.

Do's and don'ts

Accessibility

• A virtualised grid carries aria-rowcount and aria-rowindex. A screen reader counts the DOM, so a window of thirty rows out of three hundred and forty is announced as a table of thirty — see Virtual scrolling.
• A static table, not a grid widget. Cells are not tab stops; a screen reader moves between them with its own table commands. Arrow-key cell navigation is not provided, and this bullet used to say it was.
• A real <table> with <th scope="col">. Div-based grids lose screen-reader table navigation entirely.
• Sorting is yours. The component renders rows in the order given. If you sort, put a real button in the header and aria-sort on the sorted column, and say the order in words above the grid.
• DOM order equals visual order. Never reorder with CSS — announced order must match seen order.
• Selection is yours. The component has none. If you add it, use aria-selected and a cue that is not colour.
• Live updates announce through one polite summary region — "2 new cases" — never by making rows live regions.
• Sticky headers are disabled at high zoom and the grid reflows rather than scrolling horizontally at 320 px.
• Row actions are reachable by keyboard without entering a roving-tabindex maze; the primary action is a link or button in the last cell.

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 — Completeness dominates here: every case in scope is visible. Accuracy is secondary but real — the row opened is the row intended.
• Efficiency — Time to locate the highest-acuity case, and the number of scrolls, sorts and filters needed to get there.
• Satisfaction — Trust that the queue is complete and genuinely in the order it claims. A single discovered omission costs more than a hundred correct renders earn.

Clinical safety notes

• No persisted sort or filter. (you) Mitigates: a clinician inheriting a colleague's view and believing it is the default.
• Non-default state stated in words. (the component) Mitigates: a re-sorted queue being read as clinical priority order.
• Criticals bypass filters. (you) Mitigates: the highest-acuity patient being filtered out of view.
• Rows staged, never inserted under the pointer. (you) Mitigates: wrong-patient selection from a queue reordering mid-reach.
• Density never removes information. (you) Mitigates: identifiers dropped to fit more rows.
• Partial load raises an alarm. (you) Mitigates: silent incomplete coverage.
• Export contains everything in scope. (you) Mitigates: a handover or audit document that silently inherits a filter.
• Empty state proves liveness. (the component says why it is empty; proof of life is you) Mitigates: a failed pipeline reading as a quiet ward.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/data-grid.json

<DataGrid
  caption= "Triage worklist — 19 cases, newest first" 
  columns={columns}          // each declares header, unit and whether it is numeric
  rows={cases}
  rowKey={(c) => c.id}
  density= "comfortable" 
  empty={<EmptyState title= "No cases waiting"  searched= "this ward, last 24 h"  />}
/>

// Sorting, filtering and the staging of incoming rows are the caller's.
// The component does not persist them, and the rules above say what a
// correct implementation has to do — including that a new row never
// inserts itself under a pointer.

What the component takes. This table used to list defaultSort, persistState, stageIncoming, bypassFilter, onRowActivate — 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.
• Triage worklist — this component's principal use.
• Alert Banner — the compact variant used inside rows.
• Scaling & displays — row height on touch.
• Typography — tabular numerals in columns.