API reference

Every prop, option and column field, with its type, its default and what it does. The feature pages explain why; this page is for looking something up.

It is kept in step with the types: a change to a prop, an option or a column field updates this page in the same change. The types themselves are the final word: GridwrightProps and UseGridwrightOptions in src/react/types.ts, ColumnDef in src/core/types.ts, and each add-on's options type beside its factory.

• <Gridwright /> and useGridwright
• Columns
• Core add-ons: sorting, selection, pagination, staleNotice
• Add-ons: search, columnFilters, exportMenu, rowActions, inlineEditing, treeData, rowDetail, virtualRows, urlSync
• Parts, for a layout composed by hand
• Class names

TRow is your row type throughout.

<Gridwright /> and useGridwright#

<Gridwright /> takes everything in the three tables below. useGridwright(options) takes the Data and engine and Features tables and returns the instance you pass to <Gridwright instance> or <GridwrightProvider instance>.

Data and engine#

Features#

Presentation and translation (<Gridwright /> only)#

What useGridwright returns#

Columns#

A column is a plain object. Only id is required.

What the engine reads#

What React renders#

An actions column is an ordinary column whose cell renders buttons. It holds no value, so it opts out of everything that reads one. Buttons in a cell keep their own clicks: pressing one neither selects the row under selectOnRowClick nor opens a rowActions() menu. Name the row in each button's accessible name, because "Delete" read in a list of forty says nothing about which row.

const actions: GridwrightColumn<Person> = {
    id: 'actions',
    header: 'Actions',
    accessor: () => null,
    sortable: false,
    filterable: false,
    searchable: false,
    exportable: false,
    layout: { pinned: 'right', resizable: false }, // read by columnLayout(), if listed
    cell: ({ row }) => (
        <button type="button" aria-label={`Delete ${row.name}`} onClick={() => remove(row.id)}>
            <TrashIcon aria-hidden="true" />
        </button>
    ),
};

<Gridwright columns={[...columns, actions]} data={people} />

Beside a column like this, list rowActions({ items, trigger: 'contextmenu' }) if you want the menu as well. A menu previewed on hover opens over the row, between the pointer and the buttons.

Read by add-ons#

filter

edit

layout

The column's own width and minWidth are the starting width and the floor; see column layout.

An add-on of yours adds its own column field by module augmentation; see column options of your own.

Core add-ons#

On by default through coreAddons(). Configure one without rebuilding the list by passing coreAddons(options) back to the prop of the same name:

// Multi-row selection, no checkbox column.
<Gridwright selectionMode="multiple" coreAddons={coreAddons({ selection: { checkboxes: false } })} ... />

Dropping one entirely is still a list operation: coreAddons().filter((a) => a.name !== 'gridwright:pagination'). coreAddons={false} drops all four.

sorting(options)#

While more than one column is sorted, each sorted header's button holds <span class="gw-sort-priority" aria-hidden="true">{n}</span>, its 1-based place in query.sort.

selection(options)#

The selection itself is the engine's: selectionMode, onSelectionChange, api.toggleRowSelection.

// A list you select from by clicking rows, operable by keyboard through cellNavigation().
<Gridwright
    selectionMode="multiple"
    coreAddons={coreAddons({ selection: { checkboxes: false, selectOnRowClick: true } })}
    addons={[cellNavigation()]}
    ...
/>

checkboxes: false needs a replacement control. The selection state, aria-selected on rows and aria-multiselectable on the table keep working, but without checkboxes the only built-in way to toggle a row is selectOnRowClick, and its keyboard route is Space on a focused cell, which exists only with cellNavigation(). checkboxes: false with neither is a grid nobody can select from by keyboard; drive it yourself through api.toggleRowSelection.

A row click also runs the grid's own onRowClick, first, so it sees the selection as it was before the click. With rowActions() at its default trigger, or 'click', the same click also pins the row menu. Pass rowActions({ items, trigger: 'hover-contextmenu' }) to leave the click to selection: the menu still previews on hover and focus, and pins on right-click and the context-menu key.

pagination(options)#

staleNotice()#

No options. The banner above the table when a refresh failed and the previous rows are still shown.

What the core add-ons decide#

Exported from apsw-gridwright/react as plain functions, for another view of sorting, selection or pagination: an add-on of your own with the same name, or the MUI package, which is built on these and nothing private. A view that calls them says and does what the native one does.

MUI: apsw-gridwright-mui#

A second package, for applications built on MUI (@mui/material 7 or 9). Pass muiAddons() where coreAddons() would go. Its README covers installation and what does and does not follow the theme.

The views take the options, defaults and names of the add-ons they replace, so a grid cannot list both views of one feature, and locale packs and message overrides apply to both.

Add-ons#

search()#

No options. The search box, first in the toolbar. What it matches is set per column with searchable and formatValue; how fast it asks a server, with queryDebounceMs.

columnFilters()#

No options. Per column: filterable and filter (see Columns). See filtering.

exportMenu(options)#

markdownReportFormats(options) returns two formats for formats: a .md file and a PDF through the print dialog.

See exporting.

rowActions(options)#

An item

inlineEditing(options)#

Which columns are editable is the column's edit (see Columns).

Starting and finishing an edit. An editable cell renders its value inside a button.

A click on an editable cell opens the editor and does not reach onRowClick. When commit rejects, the cell shows the error and a screen reader hears it.

When the editor closes from the keyboard (Enter, Escape, choosing an option, toggling a checkbox), focus returns to the cell's button, so a keyboard reader stays in the grid. Clicking away leaves focus where the click put it.

treeData(options)#

See tree data.

grouping(options)#

Collapsible group headers, one per distinct value of a groupBy column, and a column's aggregate computed for each group and, with summaryRow, for the whole result. Runs after filtering, search and sorting, so a group sees the rows they left. Cannot be listed with treeData().

A column declares what it aggregates with aggregate (above): sum, avg, min, max, count, or (values, rows) => unknown for anything else. Grouping needs every matching row in memory, the same as a plain array: it refuses a source that paginates for itself unless serverGrouped says the source grouped already. ungroupedRows(rows) (from apsw-gridwright) turns the rows api.getMatchingRows() answers on a grouped grid — group headers and member rows both — into your rows alone, for an export or anything else that wants a flat list.

columnLayout(options)#

Resize handles in every header, draggable headers, a column picker in the toolbar, and sticky pinned columns. The table gets table-layout: fixed while this add-on is listed, and its cells truncate instead of wrapping. Reordering is by drag or by Ctrl/Cmd + arrow on a focused header, and the order reaches the engine, so an export follows it. Inside the grid, useColumnLayout() gives the controller the picker, the handles and the drag all use; see column layout.

density(options)#

density({ initial?, levels?, rowHeights?, control?, onChange? }) lets a person choose compact, comfortable or spacious rows, and puts data-gw-density on the root. Defaults: comfortable (the grid as it is), all three levels, rowHeights { compact: 32, spacious: 52 }, a toolbar select (control: false for none). onChange(level) is how you store the choice; initial is how you restore it; the package keeps no storage. useDensity() returns { level, levels, setLevel } (it throws where the add-on is not listed) and useOptionalDensity() returns null there. The active height is published to virtualRows(). See density.md.

wcag(options)#

wcag() sets the grid to WCAG 2.2 AA where the default is not, and puts data-gw-wcag="aa" on the root. options is an empty object, reserved so a level can be added later. It adds no control and no message. The stylesheet reads the attribute: the row checkboxes and the tree, group and row-detail toggles are 24 px (--gw-target-min), --gw-text-muted, --gw-border and --gw-border-strong take values that pass 1.4.3 and 1.4.11, and under forced-colors: active the focus ring, cursor cell, selected row, sort state, resize line and disabled controls use system colours. A grid that does not list it is unchanged. With muiTheme() the theme's colours win. With columnLayout() it also adds move and width buttons to each row of the column picker. It also scrolls the table's wrapper back when focus lands under the sticky header or under a column pinned to either edge, so a focused element is never left covered (a handler on the root's onFocus). useWcagEnabled() returns whether the add-on is listed (false elsewhere, never throws). See accessibility.md.

responsive(options)#

responsive({ initialWidth? }) follows the width of the grid's container. A column's responsive: { hideBelow } hides it below that many pixels (view only: still sorted, filtered, searched, exported). useContainerWidth() returns the width in pixels, or null. See responsive.md. stackBelow draws the rows as cards below that many pixels (ignored beside virtualRows()); initialWidth is the width assumed until one is measured. An add-on's contribution may carry whenNarrow: { below, contribution }, viewHiddenColumns and cardLayout; useMediaQuery(query) is the hook rowActions() uses for (hover: none).

rowDetail(options)#

An expandable panel under a row. See expandable rows.

useRowDetail() returns the controller from anywhere inside the grid: expanded, isExpanded, allows, expand, collapse, toggle, expandAll, collapseAll. expandAll() covers the rows the grid is currently holding and makes no claim about pages it has not fetched.

Throws when listed with virtualRows(): windowing places rows by a fixed height and a panel is as tall as its content.

cellNavigation(options)#

Spreadsheet-style cursor movement: one Tab stop into the grid, then the arrow keys. See accessibility.

No key fetches a page. A paginating source that sends no total leaves isTotalExact false, and the grid then knows only that another page exists — so there is no last row to jump to. Ctrl+End stops at the last row held rather than inventing one or paging until the source runs out.

Arrow keys inside a form control are left alone, so an inline editor, a <select> in a cell renderer or anything contenteditable keeps them.

Controls inside cells are operated from the cell. A button, link or checkbox inside a body cell is taken out of the Tab order, so Tab leaves the grid in one press rather than visiting every row's checkbox. Enter, Space or F2 on the focused cell operates it instead: a button, link or checkbox is clicked, and a text field or select is focused. When a cell holds several controls, the first that is not a disclosure toggle wins, so Enter on a tree cell with an editable value edits it while the arrows expand and collapse. A key pressed on the control itself stays the control's.

The built-in controls do this themselves. A control in a cell renderer of your own does it with useCellTabIndex(), which returns -1 while the cursor visits that cell and undefined otherwise:

function ProfileLink({ person }: { person: Person }) {
    return <a href={person.url} tabIndex={useCellTabIndex()}>{person.name}</a>;
}

// A component, so the hook runs inside it rather than inside the grid's render.
const columns = [{ id: 'name', header: 'Name', cell: ({ row }) => <ProfileLink person={row} /> }];

Pass the column id from an extra column of your own. With includeExtraColumns: false the cursor does not visit extra columns, so their controls, the selection checkbox among them, keep their Tab stops. The header's sort buttons keep theirs too, unless headerRow: true brings the header into the cursor.

The header row is opt-in. With headerRow: true the grid is one Tab stop including the headers: the cursor opens on the first row of data, ArrowUp reaches the header of the same column, Ctrl/Cmd + Home goes to the first header, and Enter, Space or F2 on a header sorts by it (Shift+Enter adds the column to the sort, as Shift-click does). The built-in sort button, and the MUI one, leave the Tab order in that mode. A sorting view of your own does the same with useHeaderCellTabIndex(), which returns -1 while the header is visited and undefined otherwise. Controls beside the label, a filter button or a resize handle, keep their Tab stops. A cursor on the header has rowId HEADER_ROW_ID, which onActiveCellChange and useCellNavigation().activeCell report. Under grouping() the cursor passes over a group header: it is one cell spanning the row, and its toggle is a Tab stop.

Copying. The platform's copy shortcut — Ctrl+C, Cmd+C or Ctrl+Insert, whichever the reader's system uses — copies the selected rows that are loaded, with a header row, or, with nothing selected, the cell under the cursor. The clipboard gets tab-separated text and an HTML table, so a spreadsheet pastes cells and a text editor pastes lines. Cell text is resolved exactly as an export resolves it (exportValue, then the column's text), with the same formula guard, and every cell is escaped in the HTML. Text the reader selected with the pointer is copied as that text; a copy inside a form control is the control's; the selection checkbox cell and a column with exportable: false copy nothing of the grid's. Announced through the live region, under gridwright:cell-navigation as copiedRows (plural) and copiedCell.

It runs in the browser's own copy event rather than through navigator.clipboard, so it needs no permission, works on a plain-HTTP page and inside an iframe with no allow="clipboard-write", and behaves the same on Windows, macOS, Linux and ChromeOS. What a copy guards against, and what it leaves to you, is under Security.

useCellNavigation() gives a control of your own the same cursor — activeCell, columnIds, isActive(rowId, columnId) and focusCell(cell) — and useOptionalCellNavigation() returns null where the add-on is genuinely optional.

virtualRows(options)#

Replaces the page controls with the scrollbar. Inside the grid, useVirtualScroll() gives scrollToIndex(index). See virtualization.

urlSync(options)#

Keeps search, sort, filters and page in the URL. See the view in the URL.

UrlSyncOptions#

UrlSyncAdapter is { getParams(): URLSearchParams; setParams(params, mode: 'push' | 'replace'): void; subscribe?(onChange): Unsubscribe }. getParams is read on every render; setParams receives every parameter, the grid's own and the rest.

The parameters are q, sort, f, page (from 1) and size, each written only when it differs from the grid's starting query. The linked query is applied as initialQuery, and as pageSize when the URL names a size, so it wins over the pageSize prop at mount. Under virtualRows() the page is not synced.

The codec is exported on its own:

Parts#

For a layout composed by hand under <GridwrightProvider instance={useGridwright(...)}>.

Class names#

classNames on <Gridwright /> or <GridwrightProvider> adds your class beside the built-in gw- class of each part. The stylesheet's CSS custom properties are the other way to theme; see theming.