Card

A card is a frame around content that belongs together. children is the only part it needs; the heading, the sections and the footers are yours to pass or leave out. What the card supplies beyond the frame is a set of states — loading, empty, errored, collapsed — that it renders for you.

The props below are CardV2’s. A plain Card also exists with two props — elevated and $matchCardV2 — and it is the older container rather than what this page documents. Its source marks it deprecated, and it is still load bearing: a Tooltip’s surface is that component with a shadow on it, so the old card cannot be deleted while tooltips exist.

heading is not a node. It takes title as a string, plus actions, menuActions, sticker, leftDecorativeIcon and headingProps, and PDS builds the elements from them: actions is a list of labels and handlers that becomes buttons, and menuActions becomes a dropdown behind a single overflow control.

Passing a node as title is not a way around that. PDS copies the title into an aria-label, so a node arrives at a screen reader as “[object Object]” — measured while building the figure above.

footer takes an array and renders it as one paragraph with the items separated by a dot; it is for metadata, which is what the figure’s Footer callout describes. footerContent renders whatever you give it, as is. If the footer contains a button, that is the prop you want.

Use a card to separate a group of content from what surrounds it. That is the whole mechanism, and it is why two of them nested draw the same boundary twice: the inner border stops meaning anything, because there is nothing outside it that it is distinguishing the content from. A page made entirely of cards has the same problem at the other scale.

For structured, comparative data use a Table rather than forcing rows into cards. For separate views of the same area use a Tab Bar, and for a message about the state of the system use a Banner.

A heading action, a body link and a whole-card click are three targets inside one boundary, and a reader aiming at the card cannot tell which one they will hit. Pick one. Where the card itself is the target, it is a single interactive element wrapping the content rather than a handler on the container, which is also the only version a keyboard can reach.

loading draws a shimmer in place of the content, at 200px unless loadingProps.height says otherwise. empty replaces it with a message that defaults to “No data collected” and is set by emptyProps.message. Both are the card’s job rather than the caller’s, so a card does not need a wrapper deciding which of three trees to render.

errored forces the error state, and the card is also an error boundary for its own content: anything that throws inside it renders the same state instead of taking the page down. One asymmetry to know about — erroredProps.onError fires only for errors that bubble up from children, not when you set errored yourself.

collapsible with defaultCollapsed adds a fourth state, a card that starts closed. The chevron that opens it is transparent until the heading is hovered or focused, so a collapsed card does not currently look collapsible from across the page.

sticky defaults to true, which is the opposite of how the props table reads: a card’s heading and footer pin themselves while the body scrolls unless you pass sticky={false}. That is the right default for a long record and the wrong one for a short card inside a scrolling page, where a heading pins for 40px and then releases.

fullHeight renders the content at full height; the prop’s own description calls it a hack for cards that don’t use sections.

Card.Stacked takes several cards and renders them as one surface with dividers between them. Card.Section adds a section inside a card, with its own heading, loading and empty states.

The card’s own heading renders as h2 and a section heading as h3, chosen so the document outline matches the visual one. That holds only if the card sits directly under the page’s h1. Where it sits deeper, headingProps.as overrides the level, and it is the only way to — the level is not derived from where the card is on the page.

The error state’s default text is ”🔍 Oops, something went wrong loading this card.” — an emoji, an apology and no information about what failed or what to do next. Set erroredProps.message to something that says which part of the record could not load. See Writing for what a message owes the reader.