@azrico/reactgrid

Private React data grid package for Azrideus' projects.

Usage

import { AzGrid } from '@azrico/reactgrid';
import '@azrico/reactgrid/dist/src/themes/azgrid-theme.css'; // optional colours

const columns = [{ name: 'name', header: 'Name', defaultFlex: 1 }];
const rows = [{ __table_id: '1', name: 'Alice' }];

<AzGrid theme="light" columns={columns} dataSource={rows} />;

The component imports grid.css (layout and structure, no colours) itself. azgrid-theme.css is the optional token preset: it paints every element from the --azgrid-* variables below with built-in light and dark fallbacks. Without it the grid renders unpainted and inherits the page's colours, so you can ship your own stylesheet against the stable azgrid__* class names instead.

Peer dependencies: react, @tanstack/react-table (>= 8.20) and @tanstack/react-virtual (>= 3.10). Upgrading from 1.x? Read MIGRATION-2.0.md: gridOptions is gone and every option is a top-level prop.

Props

Every x / defaultX / onXChange trio works controlled (pass x) or uncontrolled (pass defaultX).

Data

Columns

Sort and filter

Built-in operators: string contains, eq, neq, startsWith, endsWith; number eq, neq, gt, gte, lt, lte, inrange; select eq, inlist; bool eq.

Rows

Row reorder

With onRowReorder the user can drag a row to a new position with the mouse, or move the active row with Alt+ArrowUp / Alt+ArrowDown. The grid doesn't change its data: rows is a new array of the loaded top-level rows in their new order (the same row objects), pass it back as the dataSource. data is the moved row, fromIndex and toIndex its index in the loaded rows before and after the move.

const [rows, setRows] = React.useState(initialRows);
<AzGrid columns={columns} dataSource={rows} onRowReorder={({ rows }) => setRows(rows)} />;

Reordering is off while the rows are sorted (the shown order isn't the data order), with allowChildRows and with pagination: 'remote'. A row with an open cell editor can't be dragged. Dragging uses native HTML5 drag and drop, so it works with a mouse, not on touch screens. A dragged row lands after a row below it and before a row above it. While dragging, the row gets azgrid__row--dragging and the row under the pointer azgrid__row--drop-after or --drop-before, drawn as a line in --azgrid-accent.

To fit n rows without a scrollbar, give the grid get_grid_height(n, rowHeight, headerHeight) px of height: headerHeight + 1 + n * rowHeight + 2 (the header's 1px bottom border and the grid's 1px top and bottom border of the default theme). Add the filter row, footer and pagination bar when they are shown.

Tree and details

Selection

Editing

Keyboard and events

Misc

Column definition

Grid API

gridRef.current exposes:

DOM classes

The grid renders stable BEM class names. Style or query them freely. They are exported as AZGRID_CLASSES.

Header menu items get a modifier naming the entry: --sort-asc, --sort-desc, --unsort, --columns (submenu trigger), --column (a show/hide checkbox in the submenu, also carries data-column) and --custom (columnMenuItems). State modifiers: --active (current sort, or isActive of a custom item), --checked (visible column) and --open (submenu trigger while its submenu is shown).

Rows get --odd/--even, --selected, --active, --expanded and --editing modifiers, and --dragging, --drop-before/--drop-after during a row reorder. Cells get --selected, --active, --editing, --readonly, --pinned-left/--pinned-right and --pinned-edge modifiers. Header cells get --sortable, --sorted-asc/--sorted-desc and --resizing modifiers.

Saved column widths

Set gridId to keep the column widths a user resizes across reloads. Widths are saved in localStorage and matched to columns by name.

import { AzGrid, setGridStorageScope, clearColumnSizes } from '@azrico/reactgrid';

setGridStorageScope(user.id); // once, before the grids render, so users of one browser don't share widths

<AzGrid gridId="current-stock" columns={columns} dataSource={rows} />;

clearColumnSizes('current-stock'); // reset, takes effect when the grid remounts

A column's width is used as its defaultWidth when gridId is set, so it can be resized.

Accessibility

The grid exposes ARIA grid semantics, so screen readers and automation tools can read it from the accessibility tree.

New props:

• ariaLabel?: string on the grid sets the accessible name of the grid.
• ariaLabel?: (value, data) => string on a column sets aria-label on its cells. Use it for icons, badges or values whose visible text isn't descriptive.

const columns = [{ name: 'status', header: 'Status', ariaLabel: (value) => `Status: ${value}` }];

<AzGrid ariaLabel="Orders" columns={columns} dataSource={rows} />;

Override any cell attribute with the column's cellDOMProps / headerDOMProps. Values you set there are kept. An onRenderRow prop runs after the grid's own row attributes are set, so it can change them too.

Themes

Use theme="light" (default), theme="dark", or a custom name. The grid wrapper gets azgrid-scope and azgrid-theme-<name>; the portaled column and context menus (.azgrid-column-menu, .azgrid-context-menu) get the same theme class so they read the same variables. Custom names use light fallbacks for unspecified variables.

dark remains a deprecated alias. theme takes precedence.

Set --azgrid-* variables on a wrapper, :root, or a theme class. Each grid can use a different palette. Host variables always win: the theme file only declares --azgrid-preset-* fallbacks, never public defaults.

<div className="my-grid">
  <AzGrid theme="light" columns={columns} dataSource={rows} />
</div>

.my-grid {
  --azgrid-accent: #345b93;
  --azgrid-header-bg: #edf2f8;
  --azgrid-row-bg-hover: #e4ecf7;
}

Row states are painted in this order (later wins): zebra odd/even, tree rows, active, hover (also while the row's context menu is open), selected. Pinned cells copy the row's current background so they stay opaque while scrolling.

Check the stylesheets with node config/check-theme.cjs; regenerate the preset blocks and the table below with node config/generate-theme.cjs after editing the token manifest in that file.

CSS variables

All variables have light/dark fallbacks. Use valid CSS values for the named property. --azgrid-locked-column-shadow accepts a complete box-shadow value. --azgrid-header-height is not a token: the grid sets it on its root from the measured header so the filter row can stick under it.

example

See src/example.tsx for light, dark and a complete custom deco palette.

Custom renderers must style their own content. External menu portal containers need azgrid-scope, the matching azgrid-theme-<name> class and the host variables.