Data & collectionsBrick 0.1.2

Data Grid

Data Grid presents tabular data with Atom-owned cell navigation, row selection, active-cell semantics, and sortable-header activation. Brick supplies the finished visual recipes; applications own data transforms and surrounding controls.

Live example

Built from the published package

Interactive

Current projects
Project	Status
Atom	Published
Brick	Ready

Choose with confidence

Know when Data Grid is the right part

Use it when

Use Data Grid when people must move through cells with arrow keys or select rows.

Choose another path when

Use Table for static comparison, Grid for page layout, and Tree Grid for hierarchical rows. Data Grid does not provide editing, filtering, pagination, column resizing, virtualization, schemas, or enterprise data processing.

Installation and imports

tsx

import { DataGrid } from "@flowstack-ui/brick";
// or import { DataGrid } from "@flowstack-ui/brick/data-grid";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/data-grid.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Quick start

tsx

<DataGrid.Container>
  <DataGrid.Root aria-label="Projects" columnCount={2} rowCount={2}>
    <DataGrid.Caption>Current projects</DataGrid.Caption>
    <DataGrid.Header>
      <DataGrid.Row rowIndex={1}>
        <DataGrid.ColumnHeader columnIndex={1}>Project</DataGrid.ColumnHeader>
        <DataGrid.ColumnHeader columnIndex={2}>Status</DataGrid.ColumnHeader>
      </DataGrid.Row>
    </DataGrid.Header>
    <DataGrid.Body>
      <DataGrid.Row rowIndex={2} value="atom" selectable>
        <DataGrid.Cell columnIndex={1}>Atom</DataGrid.Cell>
        <DataGrid.Cell columnIndex={2}>Ready</DataGrid.Cell>
      </DataGrid.Row>
    </DataGrid.Body>
    <DataGrid.Footer />
  </DataGrid.Root>
</DataGrid.Container>

Visual recipes and states

Line separates rows; outline adds outer and column boundaries. Size changes typography and row metrics, while density changes block padding. Hover, selected, active, disabled, and sorted paint is driven by Atom state attributes without moving cell geometry.

Keyboard, selection, and sorting

Root is the single focus target and exposes the active descendant. Arrow keys move by cell, Home/End move within a row, PageUp/PageDown move by row, and Ctrl/Meta+Home or End reaches the first or last cell. Space applies Atom's row selection behavior. Disabled cells and rows are skipped according to Atom's contract.

Sorting is controlled by the application. Give a one-based indexed ColumnHeader onAction, update the data and sortDirection in application state, and render the decorative SortIndicator. Pointer activation and Enter invoke onAction; only the sorted header should expose a direction.

tsx

<DataGrid.ColumnHeader columnIndex={1} sortDirection={direction} onAction={sort}>
  Project <DataGrid.SortIndicator />
</DataGrid.ColumnHeader>

Compose external Toolbar and Pagination components around the grid when those features are needed. Cells should remain non-editing in this version.

Examples

The quick start and controlled sorting examples above cover the canonical composition. Use controlled value/onValueChange for application-owned row selection and controlled activeCell only when the application must observe or restore navigation.

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Exports

DataGrid, DataGridContainer, DataGridRoot, DataGridCaption, DataGridHeader, DataGridBody, DataGridFooter, DataGridRow, DataGridColumnHeader, DataGridCell, DataGridSortIndicator, DataGridContainerProps, DataGridRootProps, DataGridCaptionProps, DataGridHeaderProps, DataGridBodyProps, DataGridFooterProps, DataGridRowProps, DataGridColumnHeaderProps, DataGridCellProps, DataGridSortIndicatorProps, DataGridVariant, DataGridSize, DataGridDensity, DataGridCaptionSide, and DataGridCellAlign are available from root and subpath imports.

Root recipes

Prop	Values	Default
`variant`	`line`, `outline`	defaults to `"line"`
`size`	`sm`, `md`, `lg`	defaults to `"md"`
`density`	`compact`, `comfortable`, `spacious`	defaults to `"comfortable"`
`side` (Caption)	`top`, `bottom`	`bottom`
Cell/header `align`	`start`, `center`, `end`	`start`, or `end` when numeric
Cell/header `numeric`	boolean	`false`

Atom props remain available, including selection state, active-cell state, direction, looping, wrapping, disabled/read-only state, indexes, counts, sortDirection, composition, events, and refs. Physical native align values are deliberately replaced by logical values.

Shared responsibility

Accessibility

Provide a stable accessible name through Caption, aria-label, or aria-labelledby. Keep all indexes one-based and counts truthful, including when the application displays a window of a larger data set. Selection state, disabled state, sorting, and the active descendant are announced by Atom; SortIndicator is always decorative.

Responsive behavior

Author Container when wide content needs horizontal overflow. It never appears implicitly and does not alter grid semantics. Logical alignment mirrors under RTL, while numeric content uses tabular figures.

Stable visual contract

Styling and tokens

Customization

Choose a closed recipe first, then override documented public variables on a deliberate local scope. Classes, styles, slots, native props, and Atom composition remain available.

Tokens and CSS hooks

Stable classes use .brick-data-grid, .brick-data-grid-container, and .brick-data-grid__*; slots use matching data-grid-* names. Public variables use --brick-data-grid-* and cover inline size, borders, radius, section surfaces, cell spacing, row size, caption, active outline, selected/hover surfaces, disabled opacity, and sort-indicator geometry. Prefer recipes before scoped variable overrides.

Public state hooks are data-variant, data-size, data-density, data-side, data-align, data-numeric, and data-slot. Atom additionally exposes its behavioral state attributes.

Public variables:

--brick-data-grid-inline-size
--brick-data-grid-min-inline-size
--brick-data-grid-border-color
--brick-data-grid-border-width
--brick-data-grid-radius
--brick-data-grid-header-background
--brick-data-grid-header-foreground
--brick-data-grid-body-background
--brick-data-grid-footer-background
--brick-data-grid-cell-foreground
--brick-data-grid-cell-padding-inline
--brick-data-grid-cell-padding-block
--brick-data-grid-row-min-block-size
--brick-data-grid-caption-foreground
--brick-data-grid-caption-gap
--brick-data-grid-active-color
--brick-data-grid-active-width
--brick-data-grid-selected-background
--brick-data-grid-selected-foreground
--brick-data-grid-hover-background
--brick-data-grid-disabled-opacity
--brick-data-grid-sort-indicator-size
--brick-data-grid-sort-indicator-color

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground