The primitive contract
The rules every part follows, render instead of asChild, merged refs and handlers, class and style functions, and structural style only.
Every part of DataGrid (Root, Grid, Header, HeaderRows, HeaderRow, HeaderCell,
Body, Row, Cell, Empty) follows the same rules.
render, never asChild
render replaces the element a part renders. Give it an element, and the part's props are merged
into it; or a function, which receives the props and the part's state.
<DataGrid.Grid render={<table />} aria-label="People" />
<DataGrid.Cell
cell={cell}
render={(props, state) => <td {...props} title={state.active ? "active" : undefined} />}
/>Props, refs and handlers
- Any prop a part does not use is forwarded to its element (
id,aria-*,data-*, handlers). refis a plain prop, merged with the part's own.- A handler you pass runs after the part's own, with four exceptions:
Rootruns the grid's keys after youronKeyDown, its header clicks (sorting) after youronClick, a press on a column resizer, a reorderable header cell, a row's drag handle, a fill handle or a body cell with cell selection on (a drag) after youronPointerDown, and a copy or a paste on a cell after youronCopyoronPaste, onRootor on itsrenderelement; a cell's handlers run before them, sopreventDefaultcancels a key, a sort, a drag or the grid's use of the clipboard. See Keyboard and accessibility, Sorting, Column resizing, Column reordering, Row reordering and Cell selection. BodyandHeaderRowdrop atransformfrom your style: the grid moves them with it. A pinned column's cells drop atransformand the insets (top,left,right,bottom,inset): they are sticky, the grid writes theirleft. A row's detail drops them too, for the same reason.
className and style
Both take a value, or a function of the part's state:
<DataGrid.Row row={row} className={(state) => (state.rowIndex % 2 ? "bg-zinc-50" : undefined)} />Structural style only
The only inline style a part sets is what places it: position (sticky on the header, the
empty state, pinned cells, a row's
detail and a group's
label), top, left, width, height, the layers'
transform, display (flex on rows with pinned columns, grid on
measured rows), the root's overflow,
box-sizing, a z-index that stacks the grid's layers (the header above the summary rows, both
above the body; with
column groups, an upper header row above the next), and on a detail margin-top (below its row's cells) and,
beside pinned cells, margin-left and flex-shrink. In a measured row, its cells and detail take
a grid-area and the cells their place as an inline start margin, with no height; a measured
detail beside pinned cells takes align-self. Your style is
merged under these keys, which always win. Nothing cosmetic is ever set: see the
unstyled example.
No text and no names
Parts render their children, or the column's renderer (an
edited cell its column's renderEditCell, your editor). They set no aria-label of their own:
name the grid yourself (<DataGrid.Grid aria-label="People">). A
column's resize handle is an element of yours too:
useColumnResizer (from /column-resize, with columnResize()) gives it its props (ARIA, data-*, the marker the grid finds it by), never a
name, a place or a look, and so does useRowDragHandle (from /row-reorder) for a
row's drag handle (hidden from screen readers: the keys move a
row from its cells), and useGroupToggle (from /row-grouping) for a group row's toggle
(its aria-expanded, never a name), and useFillHandle (from /fill) for a
fill handle (its mark, at a range's corner only).
The recursion is yours
Rows, Cells, HeaderRows and HeaderCells take a function that renders each item, so every
row and cell is written by you. Without it, they render the default Row, Cell, HeaderRow
and HeaderCell.
In Vue
@fragiola/data-grid-vue follows the same contract with Vue's own means; the parts render the
same elements, attributes and structural style (Vue primitives).
asand therenderslot, neverasChild.astakes a tag or a component. Therenderscoped slot receives{ props, state, children }: bindpropson your own element, and render the part's content with<component :is="children" />.
<DataGrid.Grid as="table" aria-label="People" />
<DataGrid.Cell :cell="cell">
<template #render="{ props, state, children }">
<td v-bind="props" :title="state.active ? 'active' : undefined">
<component :is="children" />
</td>
</template>
</DataGrid.Cell>classandstyleare fallthrough attributes, merged under the structural style, as in React (the layers and the pinned cells drop the same keys). There is no function form: style the state with thedata-*attributes, or with therenderslot'sstate.- Listeners compose in the same order: the part's own first, then yours (
@keydown,@click,@pointerdown,@copy,@paste), then the grid's onRoot, sopreventDefaultin yours cancels a key, a sort, a drag or the grid's use of the clipboard. - The recursion is slots: the default scoped slot is the children function
(
<DataGrid.Rows v-slot="{ row }">,<DataGrid.Cells v-slot="{ cell }">), and a column's renderers return vnodes (Column<TRow, VNodeChild>). - Composables return computed refs: a part composable (
useRow,useCell,useColumnResizer, …) takes a value or a getter and returns{ state, props }, bound withv-bind="props.value". - A template ref on a part is its component instance: its element is
$el; a handle on the grid is agridRef(useDataGridRef()).
In Angular
@fragiola/data-grid-angular follows the same contract with Angular's own means; the parts put
the same attributes and structural style on your elements (Angular directives).
- Your element, never
asChild. A part is an attribute directive on the element you write (<table dataGridGrid>,<td [dataGridCell]="cell">), the Angular form ofrender. A part that renders only sometimes is a structural directive on its element (*dataGridHeader,*dataGridEmpty,*dataGridRowDetailfrom/row-expansion,*dataGridSummary="'top'"from/summary-rows).
<table dataGridGrid aria-label="People">
<tbody dataGridBody>
<ng-template [dataGridRows]="columns" let-row>
<tr [dataGridRow]="row">
<ng-template [dataGridCells]="columns" let-cell>
<td [dataGridCell]="cell" #own="dataGridCell" [title]="own.state()?.active ? 'active' : ''">
<ng-container *dataGridCellContent />
</td>
</ng-template>
</tr>
</ng-template>
</tbody>
</table>classandstyleare your element's, under the structural style, as in React: the structural keys win, and the layers and the pinned cells drop the keys the engine writes from your static style (never bind those keys yourself). Style the state with thedata-*attributes, or with the part'sstate()(#own="dataGridCell").- Listeners compose in the same order: yours (
(keydown),(click),(pointerdown),(copy),(paste)) run before the grid's on the root, sopreventDefaultin yours cancels a key, a sort, a drag or the grid's use of the clipboard. - The recursion is templates:
<ng-template dataGridRows let-row>,<ng-template dataGridCells let-cell>; a column's renderers return text or a template with its context (Column<TRow, DataGridNode>,templateContent), which*dataGridCellContentrenders. - Signals all the way: inputs, outputs (
xChangeforonXChange),state()and the injection functions'{ state, props }are signals; nothing changes while the grid scrolls within its rendered window.