Documentation
Concepts

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.

render.tsx
<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).
  • ref is a plain prop, merged with the part's own.
  • A handler you pass runs after the part's own, with four exceptions: Root runs the grid's keys after your onKeyDown, its header clicks (sorting) after your onClick, 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 your onPointerDown, and a copy or a paste on a cell after your onCopy or onPaste, on Root or on its render element; a cell's handlers run before them, so preventDefault cancels 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.
  • Body and HeaderRow drop a transform from your style: the grid moves them with it. A pinned column's cells drop a transform and the insets (top, left, right, bottom, inset): they are sticky, the grid writes their left. 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:

row.tsx
<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).

  • as and the render slot, never asChild. as takes a tag or a component. The render scoped slot receives { props, state, children }: bind props on your own element, and render the part's content with <component :is="children" />.
cell.vue
<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>
  • class and style are 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 the data-* attributes, or with the render slot's state.
  • Listeners compose in the same order: the part's own first, then yours (@keydown, @click, @pointerdown, @copy, @paste), then the grid's on Root, so preventDefault in 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 with v-bind="props.value".
  • A template ref on a part is its component instance: its element is $el; a handle on the grid is a gridRef (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 of render. A part that renders only sometimes is a structural directive on its element (*dataGridHeader, *dataGridEmpty, *dataGridRowDetail from /row-expansion, *dataGridSummary="'top'" from /summary-rows).
people-grid.ts
<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>
  • class and style are 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 the data-* attributes, or with the part's state() (#own="dataGridCell").
  • Listeners compose in the same order: yours ((keydown), (click), (pointerdown), (copy), (paste)) run before the grid's on the root, so preventDefault in 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 *dataGridCellContent renders.
  • Signals all the way: inputs, outputs (xChange for onXChange), state() and the injection functions' { state, props } are signals; nothing changes while the grid scrolls within its rendered window.