Reference v2.1.0

API Reference

Everything the package exports, in one place. The surface is deliberately small: enough to render a grid, enough to write a feature module, and nothing else.

Updated in v2.1.0

Twenty-one names are new, for pivot() and flashCells(). The methods that are reached through a grid rather than imported now have a table of their own, and six exports the page had left out are listed.

Entry Points

Three, and nothing else is importable. There is no demo to run here: an import either resolves or it does not.

Specifier	Holds
`@sv5ui/datagrid`	createDataGrid, DataGrid, Grid, every feature and every accessor, plus the types behind them
`@sv5ui/datagrid/locales`	The twelve language packs, imported one at a time so only what you use ships
`@sv5ui/datagrid/xlsx`	The workbook writer. Not a feature and it needs no grid, so a grid that never exports one never pays for it
`@sv5ui/datagrid/theme.css`	The stylesheet, imported once in your app

// Everything public comes from the package root
import {
  DataGrid, Grid, createDataGrid,
  sorting, filtering, selection, getSorting, getSelection,
  type ColumnDef, type GridState
} from '@sv5ui/datagrid';

// Except the language packs, which have their own entry point so that a
// pack nobody imports is never bundled
import { enUS, viVN } from '@sv5ui/datagrid/locales';

// And the stylesheet, next to the sv5ui one
// @import '@sv5ui/datagrid/theme.css';

Components and Theming

Export	Kind	What it is
`DataGrid`	`component`	`The whole grid, in either the shorthand or the instance form`
`Grid`	`object`	`Root, Viewport, Header, FilterRow, Body, Toolbar, QuickFilter, FilterChips, ColumnChooser, DensityToggle, ExportMenu, ContextMenu, StatusBar, Pagination. Header draws FilterRow itself, so that part is only for a header of your own`
`defineDataGridConfig`	`function`	`App-wide defaults for density and slots`
`resetDataGridConfig`	`function`	`Restores the built-in defaults. Mainly for tests`
`registerDataGridIcons`	`function`	`Registers the bundled icons. Idempotent, and only needed for a grid behind a dynamic import that may load after your own icons render`
`datagridIcons`	`object`	`The icon set itself, for an app that registers icons its own way`

The Grid and Its Constants

Export	Kind	What it is
`createDataGrid`	`function`	`Creates a grid: state plus a derived row pipeline`
`getCellValue`	`function`	`A cell value from a row and a column definition`
`PIPELINE_ORDER`	`const`	`filter 100, sort 200, group 300, flatten 400, pinSplit 500, window 900`
`SNAPSHOT_VERSION`	`const`	`The version a snapshot is written with`
`SELECTION_COLUMN_ID`	`const`	`The id of the synthetic checkbox column`
`ROW_HANDLE_COLUMN_ID`	`const`	`The id of the synthetic grip column rowReorder() draws`
`RAIL_COLUMN_PREFIX`	`const`	`What the id of a rail column starts with: the column a header group folded to a rail leaves behind`
`railColumnId / railGroupIdOf`	`function`	`The rail column id for a group id, and the group id back from a column id, or null when it is not a rail`
`isSyntheticColumn`	`function`	`Whether a column id is one the grid added itself: the checkbox, the grip or a rail. None holds data, so an export or a copy of your own should skip them`
`defaultLabels / mergeLabels`	`function`	`The English strings, and how overrides fold onto a pack`

Feature Modules

Each pairs a factory with an accessor: the factory registers it, the accessor is the typed way back to its state.

Factory and accessor	Options type	Adds
`sorting / getSorting`	`SortingOptions`	`Multi-sort, cycles, null ordering`
`filtering / getFiltering`	`FilteringOptions`	`Quick filter and five column filter kinds`
`columnOps / getColumnOps`	`ColumnOpsOptions`	`Resize, reorder, pin, hide, autosize`
`selection / getSelection`	`SelectionOptions`	`Selection, clipboard and CSV export`
`editing / getEditing`	`EditingOptions`	`Cell and row editing with validation and undo`
`pagination / getPagination`	`PaginationOptions`	`Client paging and the server hooks`
`virtualization / getVirtualization`	`VirtualizationOptions`	`Row and column virtualization`
`rowPinning / getRowPinning`	`RowPinningOptions`	`Rows pinned outside filter and sort`
`rowReorder / getRowReorder`	`RowReorderOptions`	`Drag and keyboard row reorder`

Feature Modules Added in 2.0

Each is a factory and its accessor, registered in the features array like the nine above. A feature you do not register is never imported.

Factory and accessor	Options	What it adds
`grouping / getGrouping`	`GroupingOptions`	`Group by N columns, thirteen aggregators, footers, a grand total`
`showValuesAs / getShowValuesAs`	`ShowValuesAsOptions`	`A number read as a share of a total, a parent or a row`
`tree / getTree`	`TreeOptions`	`Nested children, or a flat parent id`
`masterDetail / getMasterDetail`	`MasterDetailOptions`	`A detail panel under a row`
`formula / getFormula`	`FormulaOptions`	`Calculated columns from an expression`
`advancedFilter / getAdvancedFilter`	`AdvancedFilterOptions`	`A nested condition tree beside the column filters`
`rangeSelection / getRangeSelection`	`RangeSelectionOptions`	`Cell ranges, fill handle, cut and move, clipboard`
`findReplace / getFindReplace`	`FindReplaceOptions`	`Find and replace across the rows a filter left`
`conditionalFormatting / getConditionalFormatting`	`ConditionalFormattingOptions`	`Colour scales, data bars, duplicates, top N, expressions`
`dataImport / getDataImport`	`DataImportOptions`	`CSV, TSV, XLSX and clipboard, staged in the grid`
`savedViews / getSavedViews`	`SavedViewsOptions`	`Named views, and a link carrying a whole state`
`policy / getPolicy`	`PolicyOptions`	`Masking at render, export, clipboard, search, facet and edit`
`serverRowModel / getServerRowModel`	`ServerRowModelOptions`	`Paged or infinite blocks fetched from a data source`
`commandPalette / getCommandPalette`	`CommandPaletteOptions`	`Ctrl or Cmd plus K over what the registered features offer`
`workerDataSource`	`WorkerDataSourceOptions`	`The same DataSource, filtered and sorted off the main thread. A source rather than a feature, so it has no accessor`

Feature Modules Added in 2.1

Registered the same way. pivot() refuses to share a grid with grouping(), tree() or masterDetail(), since each of them decides what a row is.

Factory and accessor	Options	What it adds
`pivot / getPivot`	`PivotOptions`	`One field gathered down the page, another across it, a measure where they meet. The columns come from the data`
`flashCells / getFlashCells`	`FlashCellsOptions`	`Marks a cell for a moment when its value changes, with a direction for a number`

Helpers

The pieces the grid uses on itself, exported so a custom renderer or a custom export path can use the same ones.

Export	What it does
`toFilterRequest(model, quickFields?)`	`The filter as it leaves for a server: always a list and a join, plus the fields a bare query applies to`
`toSortRequest(sort, defs, nulls?)`	`The sort as it leaves for a server: each column's sortField in priority order, with the side blanks land on written on every entry`
`toCsv / toTsv`	`A matrix into a CSV or TSV string. toCsv takes its delimiter as an argument and neutralizes spreadsheet formulas itself`
`rowsToMatrix / withHeaderRow / pickColumns`	`The export path in pieces, for a format the grid does not produce. pickColumns may name hidden columns`
`getCellValue`	`A cell value from a row and a column definition, accessor included`
`registerDataGridIcons / datagridIcons`	`The bundled icon set. The import registers it; only a grid behind a dynamic import needs the call`

Reached Through the Grid

Not imports. These are methods on the grid, on grid.api or on a feature's state, listed here because code outside the grid needs them most often.

Method	What it does
`getValue(node, column, purpose?)`	`One cell as a purpose is allowed to see it. The default is what the cell draws; 'export', 'clipboard', 'search', 'facet' and 'edit' are the other ways out`
`readerFor(columnId, purpose?)`	`The cellValue gate standing in front of one column, or undefined. Hoist it out of a loop over rows: it is fixed for the column`
`toggleGroup / setGroupCollapsed`	`Folds a header group, on grid.api and on getColumnOps(grid). Both announce and emit columnGroupToggled`

Helpers Added in 2.0

What your own code reaches for when it has to meet a feature halfway: read back a row the grid drew, catch what a feature throws, or reuse a calculation it made.

Export	Reach for it when
`getGridContext / getGridElement`	`Read the grid a part is drawn inside, and its root element, from context. This is how a feature's component hook reaches either: it is mounted inside the root and handed no props. Both throw outside a grid`
`aggregate`	`The number a group footer would show, computed anywhere else: a summary card, a chart, a second table`
`totalsKindOf`	`'footer' for a group footer, 'grandTotal' for the grand total, null otherwise`
`FormulaError / ShareTooLongError`	`The two errors a feature hands back rather than throwing past you, exported as classes so instanceof works. FormulaError lands in a cell; ShareTooLongError rejects a link that would not open`
`isPivotColumn`	`Whether a column id is one pivot() generated. Those ids come from the data, so this is how a predicate picks them out without writing one down`
`isDataRow`	`Narrows a node to one carrying data, skipping a group header, a footer, a detail panel and a loading row`
`isDetailNode`	`Whether a row id names a detail panel rather than a row`
`isLoadingRow`	`Whether a row is a placeholder still on its way from the server`
`isFormulaError`	`Whether a calculated cell holds an error instead of a value`
`FUNCTION_NAMES`	`The 31 function names an expression may call, for building a completion list`
`autoColumns`	`Reads a ColumnDef[] off a sample of the rows when the shape is only known at runtime`
`localStorageViews`	`The default saved-view store, and the shape to copy for a store of your own`

Feature Classes

Exported as types only. You reach an instance through its accessor rather than constructing one.

Class	What it is
`Grouping / ShowValuesAs / Tree / MasterDetail`	`What getGrouping, getShowValuesAs, getTree and getMasterDetail return`
`Formula / AdvancedFilter / RangeSelection / ConditionalFormatting`	`The same for the four that own cells rather than rows`
`DataImport / Policy / ServerRowModel`	`The same for import, masking and the server row model`
`Pivot / FlashCells`	`What getPivot and getFlashCells return. Pivot is the typed way to everything grid.api offers for a crossing, with nothing optional`
`FindReplaceState / SavedViewsState / CommandPaletteState`	`The three whose class name would collide with the feature it belongs to, so the state carries the suffix`

The xlsx Entry

Imported from @sv5ui/datagrid/xlsx, not from the package root. Nothing here is a feature and most of it needs no grid, so a grid that never writes a workbook never bundles the code that does.

Export	What it is
`buildGridXlsx / buildGridXlsxAsync / downloadGridXlsx`	`A grid as a workbook: the bytes, the bytes without blocking the tab, or straight to a download. All three take ExportXlsxOptions`
`createWorkbook / createWorkbookAsync`	`Columns and rows with no grid involved. An array of WorkbookOptions makes several sheets`
`WorkbookOptions / WorkbookSheet / SheetOptions / SheetColumn`	`A workbook, one of its sheets, and the columns and rows a sheet is built from`
`CellValue / XlsxFormula`	`What a cell may hold, including a formula rather than a value`
`StyleTable / StyleId / DEFAULT_STYLE / BUILT_IN_STYLES`	`The style pool a sheet writes against, the handle into it, the plain style, and the defaults the grid applies from a column's type`
`XlsxStyle / XlsxFont / XlsxBorder / XlsxBorderSide / XlsxAlignment / XlsxColor`	`A style is font, fill, border, alignment and numberFormat. A colour is any CSS hex, converted to Excel ARGB on the way in`
`XlsxCfRule / XlsxFormatColors / DEFAULT_FORMAT_COLORS`	`A conditional formatting rule as Excel writes it, and the palette it uses, since Excel's colours are not your theme's`
`cellRef / columnLetter / toSerialDate`	`A1 from a row and a column, A/Z/AA from an index, and Excel's day count from a Date read in local parts`
`XLSX_MIME`	`The media type, for a Blob or a response header`

Types

Grouped by what they describe. Feature state classes and grid models are exported as types only.

Types	Describe
`ColumnDef / ColumnState / ColumnType / ColumnTypeOptions / ColumnAlign / PinnedSide`	`Columns as declared and as resolved, with the two enums they read from`
`DataGridCellContext / HeaderContext / HeaderGroupCell / HeaderGroupContext`	`What a cell snippet, a header snippet and a group header snippet receive, and the group cell itself`
`StandardSchemaV1`	`The type of a column schema, re-exported from @standard-schema/spec so a column can be typed without installing it`
`BadgeColor / RowAction / EditorOption / Density`	`The small unions the built-in renderers, the actions column and density read`
`DataGridProps / GridRootProps / GridBodyProps / GridPaginationProps / GridQuickFilterProps / GridFilterRowProps / GridExportMenuProps / GridContextMenuProps / GridParts / DataGridFullWidthContext`	`Component props worth naming, the Grid namespace itself, and the context a full-width row snippet receives. Everything else takes ComponentProps`
`DataGridUi / DataGridSlots / DataGridConfig`	`Theming`
`GridState / GridApi / GridFeature / GridEventMap / GridSnapshot / DataGridOptions / PersistStateOptions`	`The grid, its api, a feature, its events, its snapshot, what createDataGrid takes and what persistState takes`
`PipelineStage / MenuContext / MenuItem / Keybinding / CellDecoration / CellDecorationContext / EventHandler`	`Everything a feature module declares, and the handler an event takes`
`CellValuePurpose / CellValueScope / CellValueReader`	`The cellValue gate: which way out of the grid is being asked about, what the hook is handed, and the reader it returns`
`CellPosition / GridSection / VirtualRange / ColumnVirtualizer / ColumnVirtualizationOptions`	`Where focus is, which band it is in, and the windows the virtualizers expose`
`RowNode / RowMeta / RowModel / RowPinSide`	`Rows as the pipeline sees them`
`SortState / SortDirection / SortRequestEntry / SortNulls / SortCycle / ToggleSortOptions`	`Sorting, including the wire shape and what toggleSort takes`
`FilterModel / ColumnFilter / ColumnFilterEntry / ColumnFilterGroup / ColumnFilterDef / FilterType / FilterJoin / SetFilterValue`	`Filtering as the model holds it, per column and per condition`
`FilterRequest / FilterRequestEntry / TextFilterOp / NumberFilterOp / DateFilterOp / PresenceFilterOp`	`The wire shape a server row model sends, and every operator name in it`
`EditorType / EditorContext / ColumnEditorDef / EditTransaction / Editable / EditMode`	`Editing, from what opens to what a commit produces`
`SelectionMode / SelectAllState / CopyOptions / ExportCsvOptions / ExportFormatter / CellMatrix`	`Selection and the clipboard and CSV paths it drives`
`RowDragState`	`The drag in flight, for a row reorder indicator of your own`
`DataGridLabels / DataGridLabelsInput / DataGridLocalePack / DataGridAnnouncerStrings`	`Localization`
`Sorting / Filtering / Selection / Editing / Pagination / Virtualization / ColumnOps / RowPinning / RowReorder`	`Feature state classes, as types only`
`ColumnModel / FocusModel / ExpansionModel / Announcer / EventBus / Virtualizer`	`Models reachable from a grid, as types only`
`GroupingOptions / Aggregation / GroupRowValues`	`How grouping is configured, the thirteen aggregators plus a reducer of your own, and the row object a group header is given`
`ShowValuesAsOptions / ShowAs`	`Reading a number as a share: of the grand total, of its parent, or of named columns in the same row. The share is a fraction, so declare the column type percent`
`TreeOptions / MasterDetailOptions`	`Nested or flat hierarchy, and which rows open a panel`
`FormulaOptions / FormulaColumn / FormulaValue / FormulaErrorCode`	`A calculated column, what one may hold, and the six codes an error reads as: #VALUE, #DIV/0, #NAME, #NUM, #LIMIT and #CYCLE`
`AdvancedFilterOptions / FilterNode / FilterGroup / FilterCondition / AdvancedFilterOp`	`The condition tree: a node is a group or a condition, a group joins its children with and or or, and the op union is the sixteen operators a condition may use`
`RangeSelectionOptions / CellRange / CopyRangeOptions`	`What ranges allow, a range as top, left, bottom and right, and what a copy carries out of one`
`FindReplaceOptions / Match`	`Find and replace, and one match as a row and column pair with the ids behind it`
`ConditionalFormattingOptions / FormatRule / FormatPaint / FormatTarget`	`The rule list, the union of the five kinds, the class and style a rule paints, and what a rule aims at: a column id, or { measure } for every crossing of one pivot measure`
`ColorScaleRule / DataBarRule / DuplicatesRule / TopNRule / ExpressionRule`	`The five rule kinds, each with the bounds or the count it reads`
`DataImportOptions / ImportFormat / ImportStep / ImportIssue / ImportDedupe / DuplicateScope`	`The wizard: what it accepts, which of idle, mapping or review it is on, what failed validation, and whether a duplicate is measured against the file, the grid or both`
`SavedViewsOptions / SavedView / SavedViewStorage`	`A named view as an id, a name and a snapshot, and the read and write pair a store implements`
`PolicyOptions / PolicyRule / PolicyContext / MaskKind`	`A masking rule, what it is told about the cell it is masking, and the five built-in masks: hide, redact, last4, email and initials`
`ServerRowModelOptions / DataSource / GetRowsRequest / GetRowsResult / ServerMode`	`The source the grid fetches from, the request it sends and the result it expects, and whether blocks are paged or infinite`
`PivotOptions / PivotMeasure / PivotShowAs / PivotRequest`	`A crossing as declared, one thing it measures, the seven ways a measure can be read as something else, and the crossing as a server is asked for it`
`PivotKeepRows / PivotOrderColumns / PivotValuesOn`	`The three smaller options of a crossing: which gathered rows to keep, how a measure orders the column axis, and which axis the measures stack on. Also what the matching grid.api methods take and return`
`PivotAggName / PivotShareName`	`The keys of the pivotAggs and pivotShares label maps: the nine named reductions and the seven readings`
`FlashCellsOptions / FlashWay`	`Which columns flash and for how long, and what a mark says: 'up', 'down' or 'changed'`
`FlashMark / FlashContext`	`One marked cell as getFlashCells(grid).marks holds it, and the same with its age, which is what an appearance function is handed`
`WorkerDataSourceOptions / WorkerDataSource`	`The worker source, and the handle it returns with usingWorker, setRows and dispose`
`CommandPaletteOptions / GridCommand`	`The palette, and one command as an id, a label, how it is found and what it runs`
`AutoColumnsOptions / GridStatus`	`What autoColumns reads from a sample, and the loading, error and onRetry a feature owning the rows sets so the body can draw a fetch without naming the feature`

Stability

Everything above is public and covered by semver. This is version 2.1.0, so the next breaking change to any of it waits for 3.0. Internal helpers stay unexported and change freely between releases.

Semver is a promise about numbering rather than about mileage. The surface below is what the library commits to; how much of it has been through a real application is another question, so pin the exact version and read the changelog before upgrading.

If you need something unexported in order to build a feature, that is a gap in the extension points rather than a reason to reach into dist.

// Public and covered by semver from 1.0 on: everything exported from the
// package root, and the two entry points above.

// Not public, and free to change between releases: pipeline transforms,
// filter compilation, the undo stack, column sizing maths, scroll
// normalization, and every file path inside dist.

// Classes the grid constructs are exported as types only. You reach an
// instance through the grid or through its accessor:
import { getSelection, type Selection } from '@sv5ui/datagrid';

const selection: Selection<Person> | undefined = getSelection(grid);
// new Selection(...) is not something the package offers.

Performance Introduction