Build a table that becomes cards on phone — same data, two shells

Overview

One row data type, one row component, two renderers. Above 720px you get a real semantic table with sortable headers. Below 720px the same rows render as cards with key/value pairs stacked vertically.

The Field worker checking jobs on their phone and the back-office clerk checking the same jobs on a desktop are doing different jobs. The phone user can't read a 7-column table on a 380px screen; the desktop user shouldn't be punished with a card list when they have 1400px of real estate. Both should see "the same data" in shapes that fit.

Don't horizontally scroll tables on phone. A horizontally-scrolling table is a sign you've given up. The user can only ever see 1 column; they have to drag back and forth to compare. Convert to cards — the row is still one logical thing, just shown vertically.

Skip this recipe if your table is read-only and short (a flat card list works on both). Skip if you have heavy editing/bulk actions — phones aren't the right surface for power-table work; ship a leaner mobile view instead.

What you'll build

Desktop table, phone cards, and the breakpoint switch.

Required pieces

Just a row component and a breakpoint hook. CSS does the rest.

@corelithzw/react exports used here: RowCard, Button, Badge. The breakpoint hook is 8 lines.

Step-by-step build

Define columns once: key, label, format function, hidden-on-mobile flag. Both the table renderer and the card renderer read the same definition. Drift between them is the cardinal sin of this recipe.

matchMedia with a listener is the cheapest reliable way to read a breakpoint in React. Don't use window.innerWidth with a resize listener — it fires hundreds of times per drag and SSR will explode.

The component returns either a <table> or a list of cards. Both read rows and onOpen from props — no parallel state. The shell switches; the data flow stays.

The cardinal failure mode: developer never opens phone width, ships an "either" component that's broken on phone. Add a dev-only override (URL param, env var) that forces card mode regardless of viewport, and use it.

Final composition

Columns, hook, two renderers, one entry point. ~90 lines.

Variations

Three forks for "which shell wins where".

// mobile-only
export const JobList = JobCards;
// desktop-only
export const JobList = JobTable;

<th className="hide-mobile">
  Created by
</th>
// CSS
@media (max-width: 720px) {
  .hide-mobile { display: none; }
}

const ref = useRef();
const isWide = useContainerWidth(ref, 600);
return (
  <div ref={ref}>
    {isWide ? <Table /> : <Cards />}
  </div>
);

Accessibility

Two shells means two a11y surfaces — both must work.

• Desktop uses a real <table aria-label>. Screen readers navigate by row/column. The label tells them which table they're in.
• Phone uses <ul role="list"> with <li> children. Aria-label on the list mirrors the desktop table label.
• Card content uses <dl> <dt> <dd>. A description list is the right semantic for label/value pairs — screen readers read "Due: Mon, Amount: $1,200" naturally.
• Cards are real <button>s. Whole-card tap, keyboard focus, Enter/Space — no onClick on a <div>.
• Each shell has the same focus behaviour. If desktop rows are focusable, phone cards must be too — switching shells must not change keyboard reachability.
• Don't render both shells at once. Render only the matching shell. Rendering both with display: none doubles the DOM and confuses screen readers.

Related recipes