Documentation

@kanunilabs/datagrid-react


@kanunilabs/datagrid-react / GridColumnDef

Interface: GridColumnDef<TRow>

Extended by

Type Parameters

TRow

TRow = GridRowData

Properties

absoluteSort?

optional absoluteSort?: boolean

Order a number column by MAGNITUDE (rival analysis G-SORT-01): −50 and +50 sit together, and descending puts the largest deviation first whatever its sign — a variance or profit-and-loss column. The cells keep their sign; only the order changes. Blanks stay last, and two values of equal size keep their data order.

Number columns only, and applied to calculateSortValue when the column has one. The same order comes back whether the grid sorts on the main thread or in the worker. Ignored when the column has a comparator (the comparator decides) and when the column is a grouping level, where −50 and +50 are two different groups. A server-side DataSource sorts the way its server does.


align?

optional align?: ColumnAlign


allowFormulas?

optional allowFormulas?: boolean

Cell formulas (G-EDIT-01, Enterprise editing): a value in this column that is a string starting with = is a spreadsheet formula. The data keeps the formula text; the grid shows, sorts, filters, totals and exports its RESULT. [Name] reads this row's column; A1 / A1:B3 typed in the editor are the cells on screen (columns by visible position, rows by position among the data rows) and are stored by column id and row key — {price@17} — so a later sort or filter cannot repoint them. A stored A1 that arrived with the data reads the DATA order instead. Client data only. The editor of such a column is a text box, whatever its dataType.


band?

optional band?: string | string[]

Caption(s) of the band row(s) above this column's header — 'Sales' for one level, ['Contact', 'Address'] for two.

A PATH on the column rather than a nested column tree: the flat list is what carries width, order, pinning, visibility, persistence and virtualization, so keeping the model flat means banding costs nothing in the pipeline. Adjacent columns with the same path merge into one band cell.


bandShow?

optional bandShow?: "open" | "closed"

Whether this column survives its band being collapsed (gap analysis P2.6).

  • omitted — always shown; collapsing the band does not affect it
  • 'open' — only while the band is OPEN (the detail columns)
  • 'closed' — only while the band is COLLAPSED (the summary that stands in for them)

A band with no column declaring either is not collapsible: there would be nothing to hide, and a toggle that does nothing is worse than no toggle.


calculateSortValue?

optional calculateSortValue?: (row) => unknown

Sort on a derived value (e.g. custom ordering) instead of the cell value.

Parameters

row

TRow

Returns

unknown


chartRole?

optional chartRole?: "category" | "series" | "time" | "excluded"

The column's part in the Enterprise chart panel (rival analysis, charts §E.1 #12). 'category' / 'series' make it the panel's first choice for that role; 'time' treats it as a date axis, grouped by calendar; 'excluded' keeps it out of the chart altogether — its pickers, "Chart by this column" and charting a selection. Without it the panel decides by data type.


colSpan?

optional colSpan?: (params) => number

Draw this cell across the columns after it (G-CORE-03): return how many columns it covers, itself included — 1 (or anything below 2) for an ordinary cell. Asked per DATA row, so one row can carry a heading across the whole grid while the rest stay cell by cell.

A span stays inside its block (pinned left, scrolling, pinned right) and stops at a sticky column; a longer answer is cut there. The covered cells are not drawn and the keyboard steps over them, but they are still the row's data: sorting, filtering, copying and export see every column.

Parameters

params

ColSpanParams<TRow>

Returns

number


comparator?

optional comparator?: (valueA, valueB, rowA, rowB, descending) => number

Order this column by an arbitrary rule (gap analysis P1.8) — the escape hatch for orderings no data type describes: a T-shirt size scale, a domain-specific priority, a locale rule Intl.Collator gets wrong.

Prefer calculateSortValue when the rule can be expressed as a value to sort BY. That keeps the fast paths; this one closes them for this column:

• the radix/typed-array sort cannot run — a byte order cannot be derived from a function, so the column falls back to a comparator sort; • the WORKER cannot run the query at all — functions are unclonable, so a sort touching this column stays on the main thread whatever the row count. Correctness is preserved; the speed is what is spent.

The values arrive exactly as the column produces them, null/undefined INCLUDED: a custom order usually wants to place its own blanks, and the built-in "nils last" rule would pre-empt that decision.

descending is informational — the grid already inverts the result for a descending sort. It exists for rules that must NOT flip (keeping a "Total" row last in both directions).

Parameters

valueA

unknown

valueB

unknown

rowA

TRow

rowB

TRow

descending

boolean

Returns

number


dataType?

optional dataType?: GridDataType


dateFormat?

optional dateFormat?: string

How a date column is written and typed — 'dd.MM.yyyy', 'MM/dd/yyyy', 'dd/MM/yy', any separator. Defaults to 'yyyy-MM-dd'.

Governs BOTH directions: the cell renders through it, and the editor masks keystrokes into it, so what the user types back is the shape they were shown. Ignored on any other data type.


editable?

optional editable?: boolean

Editable in an Enterprise grid with editing on. Defaults to true; set false for a computed or server-owned column so the editor never opens on it.


excelFormat?

optional excelFormat?: string

Excel number format for the column (e.g. '#,##0.00', '"$"#,##0', '0.0%'), in a plain export as well as a styled one. Without it a number column gets a plain thousands separator — currency and percent are never guessed, because guessing changes what the number means.


optional exportLink?: (row) => string | null | undefined

A link for this cell in Excel and PDF exports (G-EXP-01): the cell is written as a clickable hyperlink to the URL returned. Only http:, https:, mailto: and tel: are written — anything else (a javascript: URL above all) is dropped and the cell stays plain text.

Parameters

row

TRow

Returns

string | null | undefined


field?

optional field?: string

Property read from the row object (dot paths NOT expanded — use valueGetter).


filterable?

optional filterable?: boolean


filterOperators?

optional filterOperators?: readonly CustomFilterOperator<TRow>[]

Operators of the app's own for this column, offered beside the built-ins: a menu in the filter row, the Enterprise filter builder's operator list, the filter panel's wording and the AI state schema. See CustomFilterOperator — a filter that uses one runs on the main thread.

On the column rather than the grid because an operator's meaning belongs to the column's values ("within 5 km" on a location, "is a weekend" on a date); share one object between columns to reuse it.


flex?

optional flex?: number

Share of the grid's spare width (G-CORE-02). The columns WITHOUT flex keep their width; what is left of the grid's width is divided among the flex columns in proportion to their numbers — flex: 2 takes twice what flex: 1 does — and divided again whenever the grid is resized or a column is shown, hidden or resized. minWidth / maxWidth still hold; once the flex columns are all at minWidth the grid scrolls sideways.

width is ignored while a column flexes. A user who drags a flex column's edge, or best-fits that one column, gives it a fixed width: it stops flexing (ColumnState.flex becomes 0), which a saved layout remembers. Best-fitting ALL columns leaves the flex columns alone.


formula?

optional formula?: string

A calculated column (G-CORE-01): a spreadsheet formula over this row's columns, e.g. '[Price] * [Qty]' or 'IF([Stock] < 10; "Low"; "OK")'. Columns are written [id] or [Header text]. The column sorts, filters, groups, totals and exports like any other; it is not editable. A formula that does not compile shows #NAME? (the reason is in controller.getFormulaError(id)); one that reads itself, directly or through another calculated column, shows #CYCLE!. dataType defaults to what the formula produces. valueGetter, when also given, wins.


groupable?

optional groupable?: boolean


groupEdit?

optional groupEdit?: "proportional" | "even" | ((params) => object[])

Let the user type a new GROUP total for this column (G-GRP-02, Enterprise): double-clicking the subtotal under the column in a group row (grouping.display: 'aligned' or 'column') opens it, and the new value is shared out over the group's rows — 'proportional' keeps each row's share, 'even' gives every row the same. Works where that subtotal is a sum or an avg. A function decides the new row values itself. Needs editing; rows the user may not change keep their value.


groupInterval?

optional groupInterval?: DateGroupInterval

Group a DATE column by calendar 'day', ISO 'week', 'month', 'quarter' or 'year' instead of by the exact instant — one banner per month reading "October 2026" rather than one per timestamp. Applies to client-side data; a server-side source groups the way its server does.


headerName?

optional headerName?: string


hideBelow?

optional hideBelow?: number

Hide the column while the GRID is narrower than this, in pixels — a responsive layout, not the user's choice. It is a layer of its own, like a folded band: the saved view keeps what the user chose (visible), the column chooser still shows the column ticked, and it comes back by itself once the grid is wide enough. A column the user hid stays hidden at any width. Search, filters, export and import still read the column; a row copy (Ctrl+C) takes what is on screen.


hideInChooser?

optional hideInChooser?: boolean

Never list the column in the column chooser (the toolbar's Columns, the header menu's Field chooser, the side bar's Columns panel), so the user cannot show it or hide it. For a column that exists for the grid's sake — a key, a helper the app toggles itself with visible — and not for the user's. Everything else still reads it: search, filters, export, import.


id?

optional id?: string

Stable identity; defaults to field. Required when two columns share a field.


lookup?

optional lookup?: ColumnLookup<TRow>

Value list for a code→label column. Drives the select editor, and (for a static list) the displayed text.


maxWidth?

optional maxWidth?: number


minWidth?

optional minWidth?: number


numberFormat?

optional numberFormat?: ColumnNumberFormat

How a number column is shown and typed, in the grid's locale rather than the browser's (P-3): separators, fraction digits, bounds, an arrow-key step. The cell shows the formatted number ("1.234,50" in tr with decimals: 2); the editor is a text box (inputMode="decimal", or "numeric" with decimals: 0) that opens on the plain text ("1234,5") and refuses text that is not a number in that locale ("1.5" in tr) with a validation message, leaving the value unchanged.

Precedence: a valueFormatter wins over this for the cell's text; a valueParser wins for reading what was typed (it gets the editor's text; the rounding is then its own). Bounds and the step apply either way. React grids edit with it; the plain-JS grid only shows it (and, as it does not hand its locale to the core, needs numberFormat.locale).


pin?

optional pin?: ColumnPin


reorderable?

optional reorderable?: boolean


resizable?

optional resizable?: boolean


sortable?

optional sortable?: boolean


sortCycle?

optional sortCycle?: SortCycle

The directions a header click steps through on THIS column, overriding the grid's sorting.cycle — ['desc', 'asc', null] to open a figures column at its largest, ['asc', 'desc'] to never return to unsorted. See SortCycle. Only the header click follows it; setSort can still set any direction.


spanRows?

optional spanRows?: boolean | SpanComparator<TRow>

Merge this column's cell down over consecutive rows holding the same value (gap analysis P3.1).

Computed over the CURRENT view, which is the point: sorting a column into A A A B B is what makes the merge meaningful, and the same rows unsorted merge nothing. Blanks never merge, a group banner interrupts a run, and a run of one is left as an ordinary cell.

true compares with Object.is. Pass a function for values that need their own notion of equality — a column of objects, or a case-insensitive code.

The merged block is still N cells to everything else: selection, editing, the clipboard and export see the rows the data has. Only the DRAWING is merged, which is what a reader means by it.


sparkline?

optional sparkline?: ColumnSparkline<TRow>

Draw this column's value as an in-cell chart (gap analysis P2.2).

The cell's value must be an ARRAY of numbers — a series per row. Config lives here, next to band and lookup, because it is data description rather than rendering: which numbers, and against what scale. The drawing belongs to the adapter, and the packaged renderer is Enterprise.


valueFormatter?

optional valueFormatter?: (value, row) => string

Display formatting hook (adapters render the returned string).

Parameters

value

unknown

row

TRow

Returns

string


valueGetter?

optional valueGetter?: (row) => unknown

Derive the cell value; overrides field access.

Parameters

row

TRow

Returns

unknown


valueParser?

optional valueParser?: (params) => unknown

Turn what the user typed or pasted into the value the cell stores — '1,5' → 1.5, '€12' → 12, 'yes' → true.

The built-in editors only know the data type; they cannot know that this column's users write decimal commas or a currency sign, and a grid that stores the raw text sorts '10' before '9' and totals nothing. Runs on every route TEXT takes into a cell — an editor commit (cell, row, form and popup) and a paste — and BEFORE validation, so a rule checks the value that would be stored, not the characters that were typed. Fill and undo copy values that are already stored and do not run it: a parser that is not idempotent (v * 100) would apply twice.

oldValue is the cell's current value (a pending edit included); row is the stored row. Whatever is returned is stored as-is.

Parameters

params

ValueParserParams<TRow>

Returns

unknown


valueSetter?

optional valueSetter?: (params) => boolean | void

Write an edited value into the row yourself, instead of the grid's row[field] = value.

For data the grid cannot write by key: a nested object (row.address.city behind a valueGetter), a computed column whose edit belongs in another field, or an immutable store that must be updated through its own action. Return false to say nothing changed — the grid then records no edit, fires no cellValueChanged and saves nothing, and the cell keeps showing what the row holds.

Called wherever the grid writes into your row: cell-mode editing (the Community mode), and the fill, paste, cut, undo and redo of it. The buffered modes (batch, row, form, popup) never write into the row — the change goes to your save handler — so it is not called there.

Parameters

params

ValueSetterParams<TRow>

Returns

boolean | void


visible?

optional visible?: boolean


width?

optional width?: number


wrapHeaderText?

optional wrapHeaderText?: boolean

Let this column's HEADER text wrap onto more lines instead of being cut with an ellipsis — for long captions on narrow numeric columns, where widening the column to fit its title wastes the space its numbers need.

On its own the header keeps its fixed height, so a third line is clipped; add the grid's autoHeaderHeight to let the header row grow to the tallest wrapped caption.