Skip to content
Compositions

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.

Carrara MarbleStoneHonedIn stock
White Oak PlankWoodMatteIn stock
Basalt SlabStonePolishedMade to order
Brass SheetMetalBrushedIn stock
Linen WeaveTextileWovenMade to order
Rows per page
1 - 5 of 7

Usage

@instruments/materia-ui/compositions/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 useTable 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

PropTypeDefaultDescription
childrenReactNode
classNamestring
emptyMessageReactNode

Content shown in place of rows when the table is empty.

initialColumnPinning{ left?: string[]; right?: string[]; }

Initial pinned columns (applied once).

loadingboolean
loadingMessageReactNode
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.

tableTable<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 virtualisation for large datasets.

DataGridCheckbox

PropTypeDefaultDescription
sizeDataGridControlSize

DataGridExpandToggle

PropTypeDefaultDescription
classNamestring

CSS class name

collapsedIconReact.ComponentType<React.SVGProps<SVGSVGElement>>

Collapsed icon

expandedIconReact.ComponentType<React.SVGProps<SVGSVGElement>>

Expanded icon

row(required)Row<TData>

DataGridFilterableHeader

PropTypeDefaultDescription
children(required)ReactNode
classNamestring
column(required)Column<TData, TValue>
optionsFilterOption[]

Filter options - enables the facets section

showSearchboolean

Control search: true = always, false = never, undefined = auto (> 5 options)

showSelectedTagsboolean

Show selected values as dismissible Tag pills above the filter list

DataGridProvider

PropTypeDefaultDescription
childrenReactNode
classNamestring
emptyMessageReactNode

Content shown in place of rows when the table is empty.

initialColumnPinning{ left?: string[]; right?: string[]; }

Initial pinned columns (applied once).

loadingboolean
loadingMessageReactNode
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)Omit<import("@tanstack/react-table").Table<{ aggregationFns: { sum: import("@tanstack/react-table").AggregationFnDef<any, any, unknown, number>; min: import("@tanstack/react-table").AggregationFnDef<a

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 virtualisation for large datasets.

DataGridRowSelect

PropTypeDefaultDescription
disabledboolean
row(required)Row<TData>

DataGridRowSelectAll

PropTypeDefaultDescription
disabledboolean
table(required)Table<TData>

DataGridShell

PropTypeDefaultDescription
children(required)ReactNode

Child elements

classNamestring

CSS class name

borderBorderStyle

Border style. Options: "solid" (default), "none", "dashed".

refimport("react").Ref<HTMLDivElement>

Ref to the container element

Also exports

  • constcreateExpanderColumn
  • constcreateSelectionColumn
  • constdataGridAnatomy
  • interfaceDataGridApiFetchParams
  • interfaceDataGridApiResponse
  • interfaceDataGridAppliedFilter
  • interfaceDataGridColumnFilterMeta
  • interfaceDataGridContextProps
  • interfaceDataGridProps
  • interfaceDataGridRequestParams
  • constfilterFnInValues
  • interfaceFilterOption
  • constgetAppliedFilters
  • constgetColumnFilterOptions
  • constgetColumnFilterValues
  • constgetColumnTitle
  • constgetFilterableColumns
  • constgetSortableColumns
  • constsetColumnFilterValues
  • constuseDataGrid
  • constuseDataGridTable

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

Button, Checkbox, ExpandButton, Flex, Grid, Icon, MenuItem, ScrollArea, Separator, Tag, Toggle, ToggleGroup

Used by

DataGridColumnHeader, DataGridPagination, DataGridTable, PageToolbar