Table

Problem Context

• The items share a stable set of attributes such as name, status, owner, due date, amount, count, or last updated time.
• Users need to scan down columns, compare values across rows, or find differences between records.
• The table may sit near search, sort, filters, pagination, row actions, expandable detail, or bulk selection controls.
• The product can define which columns matter, how headers map to values, and what happens at narrow widths.

Selection Rules

• Choose table when each row represents one record and each column represents the same attribute for every row.
• Use table for comparison, audit, reconciliation, inventory, queue, billing, status, and report tasks where aligned columns reduce effort.
• Use a data grid when users edit cells, navigate between interactive cells with arrow keys, or perform spreadsheet-like operations.
• Use list view when items are primarily scanned as summaries and shared columns are secondary.
• Use card list or card grid when item imagery, uneven metadata, or rich object previews matter more than column alignment.
• Use sort controls or sortable headers to change row order, but keep sorting separate from filtering and pagination state.
• Use filter panel to change which rows are included, not to rename or hide table columns without clear table-state feedback.
• Use pagination, virtual loading, or a saved view when the row count is too large for one table view.
• Avoid table when there are fewer than two comparable attributes or when every row needs a different layout.
• Avoid layout tables for positioning page content.

Required States

• Default table state with caption, visible headers, row values, and result count or context.
• Sorted table state with current sorted column and direction exposed visually and programmatically.
• Filtered table state with active criteria near the table and updated row count.
• Selected-row state when the table supports row selection or bulk action.
• Row-action state with actions associated to the correct row.
• Empty table state after filters or search remove all rows.
• Loading or updating state while table rows refresh.
• Responsive state that preserves header-to-cell meaning.
• Overflow state for wide tables with visible horizontal scroll or column-priority rules.
• Error state when rows cannot load while table structure and retry path remain visible.

Interaction Contract

• The table caption or nearby heading names the dataset and purpose, not just Table.
• Column headers identify the values below them and remain associated with cells in desktop, stacked, and horizontally scrolled layouts.
• Row headers identify each record when the first column is the record name or primary identifier.
• Sortable headers update row order, active indicator, accessible sort state, and result summary together.
• Filtering updates row membership while preserving current sort unless the design explicitly resets it.
• Pagination moves through the same sorted and filtered table without losing row meaning.
• Row actions, links, checkboxes, and expansion controls are labelled with the row they affect.
• Keyboard focus remains stable after sort, filter, pagination, row selection, expansion, or refresh.

Implementation Checklist

• Define the row object, column attributes, primary row header, caption, and optional table description.
• Use table semantics with caption, thead, tbody, th, td, scope, and row or column headers appropriate to the complexity.
• Use id and headers associations for complex grouped headers when scope alone is insufficient.
• Align numeric values, dates, status tags, and row actions consistently.
• Show active sort and filter state near the table and synchronize it with row count and pagination.
• Label row actions and selectable rows with the record identity.
• Choose a responsive strategy: horizontal scroll, stacked rows with labels, reduced columns, or a dedicated detail view.
• Handle empty, loading, error, selected, expanded, sorted, filtered, and paginated states deliberately.
• Test with keyboard, screen reader table navigation, zoom, high contrast, long labels, localized values, and narrow viewports.

Common Generated-UI Mistakes

• Using table markup to create page columns or layout spacing.
• Rendering div rows that visually resemble a table but expose no table, row, column, or header semantics.
• Omitting the caption or visible dataset context.
• Dropping column headers on mobile so values lose meaning.
• Mixing sorting, filtering, search, pagination, and column visibility into one unlabeled control.
• Turning a read-only table into an editable spreadsheet without data-grid keyboard behavior.
• Putting too many columns, long paragraphs, and row actions into a cramped table.
• Sorting formatted values by displayed text instead of raw date, amount, number, or status order.

Critique Questions

• What does one row represent, and what does each column mean?
• Can users compare values down a column and across rows without opening every record?
• Is there a caption or heading that names the dataset and table purpose?
• How are headers preserved in responsive, sorted, filtered, and paginated states?
• Are row actions, selections, and expanded content tied to the correct record?
• Has the table become an editable data grid, card list, or list view instead?