Expandable row

Problem Context

• Rows represent records such as invoices, orders, payments, events, files, alerts, support tickets, devices, permissions, or audit entries.
• Most users scan the collapsed rows first and open detail only for exceptions, verification, recent history, line items, or secondary actions.
• The detail belongs to one row and should stay near that row rather than becoming a page-level section or global panel.
• The data surface may be sorted, filtered, paginated, virtualized, refreshed, selected, or used on narrow screens.
• Some rows may have no additional detail, stale detail, permission-limited detail, or detail that loads after expansion.

Selection Rules

• Choose expandable row when the main surface is a table or list and the extra content is owned by one row.
• Use a standard table when the content should be visible for many rows at once and compared down a column.
• Use details panel when users repeatedly inspect many records and benefit from a persistent inspector beside the table or list.
• Use accordion when the content is page-level sections rather than row-owned detail.
• Use disclosure details when there is one small optional explanation near text or a form field, not repeated row detail.
• Use tree grid when expansion represents a real hierarchy of parent and child rows with row-and-column semantics.
• Use drawer, sheet, or full page when the expanded content needs long reading, primary editing, comments, history, attachments, or destructive review.
• Do not use expandable rows to hide values users must compare across all rows, such as amount, due date, owner, or status.
• Do not show expand controls for rows with no detail unless the unavailable state and reason are clear.
• Avoid expandable rows when sorting, filtering, or virtualization cannot keep expansion state attached to the correct record ID.

Required States

• Collapsed row with row identity, key values, and a labelled expand control.
• Expanded row with detail region immediately after the owning row and a labelled collapse control.
• Focused expand control, keyboard activated expansion, and focus return after collapse.
• Row with no additional detail or permission-limited detail.
• Loading, loaded, stale, failed-load, and retry states for detail fetched after expansion.
• Expanded row after sort, filter, pagination, refresh, or selection change.
• Collapsed row with hidden error, warning, count, or changed-detail summary.
• Narrow-screen state that preserves row identity and header-to-cell meaning.

Interaction Contract

• The expand control names the affected row, exposes expanded state, and controls only that row's detail region.
• Expanded content appears directly after the owning row in visual and reading order, with a heading or label that repeats the row identity.
• The collapsed row summarizes any hidden critical status, validation issue, unread activity, count, or stale detail that users need before opening.
• Sorting, filtering, pagination, refresh, and virtual loading preserve expansion by stable record ID or intentionally collapse with a visible status message.
• Rows without detail do not expose misleading active expand controls.
• Expanded content does not disrupt column alignment, sortable headers, row selection, row actions, or bulk-selection behavior.
• Secondary actions inside the expanded detail clearly apply to the owning row and preserve focus or return to the row control after completion.

Implementation Checklist

• Define which row fields remain visible, which detail fields can be hidden, and which hidden statuses require collapsed-row summaries.
• Key expansion state by stable record ID rather than visual index.
• Use a button or native disclosure control for each expandable row and include the row name or identifier in its accessible name.
• Connect the control to the row detail region with expanded state and a stable region label.
• Place expanded content immediately after the owning row or inside a semantic structure that preserves row ownership.
• Handle no-detail, loading, failed detail, stale detail, permission-limited detail, and deleted-row states.
• Decide whether multiple rows can be open, whether opening a new row closes others, and how that affects selection and focus.
• Test sort, filter, pagination, refresh, virtualization, row selection, bulk actions, keyboard, screen reader table navigation, zoom, and mobile stacking.

Common Generated-UI Mistakes

• Hiding primary columns or required decision data inside collapsed detail.
• Tracking expansion by row index so a different record appears expanded after sorting or filtering.
• Using a chevron-only button with no row identity or expanded state.
• Showing expand controls on rows with no additional content.
• Putting long forms, nested data grids, destructive confirmations, or unrelated navigation inside the expanded area.
• Moving expanded detail away from the owning row.
• Breaking table header associations or row action labels when the detail row is inserted.
• Collapsing an expanded row after refresh without explanation while the user is reviewing it.

Critique Questions

• What exact record owns the expanded content?
• Which hidden details are optional, and which need a collapsed-row warning, count, or summary?
• Can users sort, filter, paginate, refresh, and select rows without expansion moving to the wrong record?
• Would the hidden content work better as a visible column, details panel, drawer, full page, accordion, or tree grid?
• How do rows with no detail, failed detail load, stale detail, or permission-limited detail behave?
• Can keyboard and screen-reader users identify, open, review, act on, and collapse the row detail predictably?