DataGrid

Root of the DataGrid compound: merges caller layout/loading props over sensible defaults and provides the context consumed by the table parts. Requires a TanStack table instance (throws without one). Applies initialColumnPinning once on mount and auto-enables column pinning for it.

		Finish	Status
Carrara Marble	Stone	Honed	In stock
White Oak Plank	Wood	Matte	In stock
Basalt Slab	Stone	Polished	Made to order
Brass Sheet	Metal	Brushed	In stock
Linen Weave	Textile	Woven	Made to order

Rows per page

1 - 5 of 7

Usage

@desk/ui/components/data-grid

<DataGrid recordCount={MATERIALS.length} table={table}>
  <DataGridShell>
    <DataGridTable />
  </DataGridShell>
  <DataGridPagination />
</DataGrid>

Best practices

Reach for DataGrid (not Table) when you need sorting, filtering, column pinning/visibility, or pagination — Table is a plain styled HTML table with no data model.
Pass a useReactTable instance as table — DataGrid throws "requires the table prop" without one; column defs and row model live on that instance, not on DataGrid props.
Render the satellite parts (DataGridTable, DataGridPagination, DataGridColumnHeader/Filter/Visibility) inside DataGrid — they read the table + layout from its context and break outside it.
Enable features through tableLayout (columnsPinnable, columnsResizable, columnsVisibility, …) rather than styling rows manually; set initialColumnPinning to pin on mount.

Props

DataGrid

Prop	Type	Default	Description
children	`ReactNode`
className	`string`
emptyMessage	`ReactNode`		Content shown in place of rows when the table is empty.
initialColumnPinning	`ColumnPinningState`		Initial pinned columns (applied once).
loading	`boolean`
loadingMessage	`ReactNode`
loadingMode	`"skeleton" \| "spinner"`	`"skeleton"`	How the loading state renders.
onRowClick	`(row: TData) => void`		Invoked when a body row is clicked; providing it makes rows interactive.
recordCount(required)	`number`		Total row count across all pages; drives pagination and the empty state.
table	`Table<TData>`		TanStack table instance to render. Required by `DataGrid`; optional here so context can be shared.
tableClassNames	`{ base?: string; header?: string; headerRow?: string; headerSticky?: string; body?: string; bodyRow?: string; footer?: string; edgeCell?: string; }`		Per-slot class overrides for the table's structural elements.
tableLayout	`{ dense?: boolean; cellBorder?: boolean; rowBorder?: boolean; rowRounded?: boolean; striped?: boolean; headerBackground?: boolean; headerBorder?: boolean; headerSticky?: boolean; width?: "auto" \| "fix`		Presentational toggles for density, borders, sticky/pinnable columns, and row sizing.
virtualization	`{ enabled?: boolean; estimateSize?: number; overscan?: number; }`		Row virtualization for large datasets.

DataGridCheckbox

Prop	Type	Default	Description
indeterminate	`boolean \| undefined`		When true, displays an indeterminate state (dash icon). This is syntactic sugar for checked="indeterminate".
size	`DataGridControlSize`

DataGridExpandToggle

Prop	Type	Description
className	`string`	CSS class name
collapsedIcon	`React.ComponentType<React.SVGProps<SVGSVGElement>>`	Collapsed icon
expandedIcon	`React.ComponentType<React.SVGProps<SVGSVGElement>>`	Expanded icon
row(required)	`Row<TData>`

DataGridFilterableHeader

Prop	Type	Description
children(required)	`ReactNode`
className	`string`
column(required)	`Column<TData, TValue>`
options	`FilterOption[]`	Filter options — enables the facets section
showSearch	`boolean`	Control search: true = always, false = never, undefined = auto (> 5 options)
showSelectedTags	`boolean`	Show selected values as dismissible Tag pills above the filter list

DataGridProvider

Prop	Type	Default	Description
children	`ReactNode`
className	`string`
emptyMessage	`ReactNode`		Content shown in place of rows when the table is empty.
initialColumnPinning	`ColumnPinningState`		Initial pinned columns (applied once).
loading	`boolean`
loadingMessage	`ReactNode`
loadingMode	`"skeleton" \| "spinner"`	`"skeleton"`	How the loading state renders.
onRowClick	`(row: TData) => void`		Invoked when a body row is clicked; providing it makes rows interactive.
recordCount(required)	`number`		Total row count across all pages; drives pagination and the empty state.
table(required)	`Table<TData>`		TanStack table instance to render. Required by `DataGrid`; optional here so context can be shared.
tableClassNames	`{ base?: string; header?: string; headerRow?: string; headerSticky?: string; body?: string; bodyRow?: string; footer?: string; edgeCell?: string; }`		Per-slot class overrides for the table's structural elements.
tableLayout	`{ dense?: boolean; cellBorder?: boolean; rowBorder?: boolean; rowRounded?: boolean; striped?: boolean; headerBackground?: boolean; headerBorder?: boolean; headerSticky?: boolean; width?: "auto" \| "fix`		Presentational toggles for density, borders, sticky/pinnable columns, and row sizing.
virtualization	`{ enabled?: boolean; estimateSize?: number; overscan?: number; }`		Row virtualization for large datasets.

DataGridRowSelect

Prop	Type	Default	Description
disabled	`boolean`
row(required)	`Row<TData>`

DataGridRowSelectAll

Prop	Type	Default	Description
disabled	`boolean`
table(required)	`Table<TData>`

DataGridShell

Prop	Type	Description
children(required)	`ReactNode`	Child elements
className	`string`	CSS class name
border	`BorderStyle`	Border style. Options: "solid" (default), "none", "dashed".
ref	`import("react").Ref<HTMLDivElement>`	Ref to the container element

Also exports

constcreateExpanderColumn
constcreateSelectionColumn
constdataGridAnatomy
interfaceDataGridApiFetchParams
interfaceDataGridApiResponse
interfaceDataGridContextProps
interfaceDataGridProps
interfaceDataGridRequestParams
interfaceFilterOption
constuseDataGrid

Anatomy

DataGridShell

data-grid

Framed container providing context and layout for the grid

DataGridToolbar

data-grid-toolbar

Header bar with left and right action regions

ToolbarLeft

toolbar-left

Leading region for search and filters

ToolbarRight

toolbar-right

Trailing region for actions and controls

DataGridTable

data-grid-table

TanStack-powered table with header, body, and rows

Composition

Builds on

Badge, Button, Checkbox, ExpandButton, Flex, Icon, MenuItem, Popover, ScrollArea, Separator, Tag

Used by

DataGridColumnHeader, DataGridPagination, DataGridTable