Data table

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

The page owns the table. Call useDataTable in a client component, with columns built by createDataTableColumnHelper, and render <DataTable table={table} />. The page reads the selection and handles the actions from the same table, so its own buttons sit beside the table, as the Selection and Row actions examples show.

Columns are TanStack Table column definitions; meta takes the data table's own keys, listed in the API reference. Sorting, selection and column widths are TanStack state: pass initialState to start sorted or sized, or state with its change callback to control them (the Sorting and Resizing examples). A callback alone works too: the table keeps the state and calls you after each change.

Salesforce's GraphQL API returns fields as { value, displayValue }. Read .value with a meta.type, so the table formats and sorts the raw value, as an accessor function with an id:

A column's meta also takes Output field's format and link keys, so a column reads as a record's field of the same type. The cell's title and the sort keep the value:

A label that differs by row, like each account's name on its website, is a custom cell that draws OutputFieldCompactValue from @/components/wisty/output-field:

showRowNumberColumn numbers the rows before the checkboxes, as list views do. The numbers count the rows shown, so sorting or filtering data renumbers them from 1. When data is one page of a longer list, like the third page of ten, pass the rows before it as rowNumberOffset and the first row reads 21.

To sort on the server, pass manualSorting and an onSortingChange that fetches; the state carries each column's id, like [{ id: "Amount", desc: true }]. To add your own meta keys, merge into DataTableColumnMeta with declare module "@/components/wisty/data-table".

DataTable is the SLDS table as lightning-datatable renders it, on Table, with no cell buffer. Row headers are th scope="row", and cells that don't wrap clip with slds-truncate. The row number column is lightning-datatable's, each number slds-row-number in small, weak text. The select column holds Checkbox, and the actions button opens Dropdown Menu. The on-scroll spinner is SLDS's small spinner. SLDS has no Load more button or placeholder rows: Load more is slds-button_neutral, and placeholder rows are Skeleton.

Known gaps:

• No grid: the table isn't role="grid" and has no arrow keys between cells. Every control is a tab stop.
• A resize's guide line stops at the bottom of the visible rows. SLDS draws it 100vh tall.
• After a resize, widths stay in pixels when the container changes size, so the table scrolls sideways or leaves space at its end. lightning-datatable scales the columns to fit again.
• Wrap text and Clip text aren't built into header menus, as lightning-datatable adds them. The Wrap and clip example builds them with meta.headerActions.
• The arrow, chevrons and check are lucide's, where SLDS draws utility:arrowdown, utility:down and utility:check.
• The text the table adds ("Row Number", "Select all rows", "Choose a row to select", "Select …", "Show actions for …", "Show … column actions", "Sorted by …", "No items to display.", "Load more", "Loading") is English.

Tab moves through select all, each sort button, header menu button and column divider, then each row's checkbox, links and actions button. With virtualize, the focused row and its neighbours stay rendered, so Tab continues in order after you scroll away, and a row stays while its menu is open. Menus take Dropdown Menu's keys.

• Name the table with aria-label or aria-labelledby on DataTable.
• Mark the name column meta.rowHeader, or pass getRowLabel. Its value names each row's controls: "Select Acme", "Show actions for Acme". Without one, they name the row by its position: "Select row 1".
• Give a column whose header is a function a meta.label. It names the sort button, the header menu, the resize slider and the sort announcement.
• Sortable headers carry aria-sort, and a polite live region says the new sort, like "Sorted by Amount, ascending". Each column divider is a slider named "Amount column width" whose value reads "180 pixels".
• The table has aria-busy while isLoading or isFetchingNextPage; placeholder rows are hidden from screen readers. A virtualized table carries aria-rowcount and aria-rowindex, but find in page and printing see only the rendered rows.
• In Lightning Blue, a link in a selected row is 4.17:1, below WCAG AA's 4.5:1. SLDS's own stylesheet does the same.

• The table fills its container. Columns with a size keep it; the rest share what's left, at least their minSize each. When they don't fit, the table scrolls sideways inside its border.
• After a resize, every column keeps its width and the table is as wide as its columns.
• The row number column widens when the numbers reach three digits, so a number never clips.
• Values clip with an ellipsis and a title unless the column sets wrapText. Decide per column: names clip, descriptions wrap with wrapTextMaxLines.
• Without a height, the table grows with its rows. With one (className="h-96" or max-h-[60vh]), it scrolls inside itself under a header that stays in place.

• Rows re-render only when their own data, the columns, the locale or their selection changes. Define columns outside the component, or in useMemo, or every row re-renders on every render.
• Sorting runs in the browser unless you pass manualSorting. 10,000 rows sort in about 150ms to 320ms in development builds.
• Without virtualize, every row renders. Use it from a few hundred rows: 10,000 rows keep about 30 in the page. Rendering all of 2,000 rows takes 1.5s to 5s in development builds.
• A resize re-renders no rows: the width changes on the table's columns directly, and the page re-renders only as the drag starts and ends. With columnResizeMode: "onChange", columnSizing and the page update on every frame instead.

• Call table.resetRowSelection() after a bulk delete removes selected rows. The table keeps the ids of rows that leave data, so a selection survives a refetch or a new page.
• Give the table a height before passing virtualize or loadMoreOnScroll.
• Select all covers the rows that are loaded, never every record on the server. A bulk action on the selection reaches only those.
• A time column's values are times of day, like "09:30:00.000Z", and sort by the clock. An amount past 15 digits shows every digit when it's a decimal string, but two that differ only past the 15th may sort as equal.
• A relative column ("3 hours ago") counts from now, an ISO instant. Pass it when the page renders on the server, or the current time is read at render and the server and the browser can differ.
• An address value is { street, city, state, postalCode, country } and a name value is { salutation, firstName, middleName, lastName, suffix }. A cell shows either on one line ("312 Constitution Place, Austin, TX 78767, USA"), sorts by that text, and treats one with no parts as empty. A relative value is an instant and sorts by it; its date and time are in the cell's title and read after the text.
• Set enableResizing: false on a column that must keep its size. To keep widths across visits, save them with onColumnSizingChange. Restore widths from the server through initialState.columnSizing; read widths from localStorage only after the page hydrates, and pass them through state.columnSizing.
• Don't add rowNumber, select or actions columns; the table adds them, and a column of yours with one of those ids replaces it. Don't put buttons in header; use meta.headerActions.
• Never pass asChild or render.