@kanunilabs/datagrid-react / ReactGridColumnDef
Interface: ReactGridColumnDef<TRow>
Extends
GridColumnDef<TRow>
Type Parameters
TRow
TRow = GridRowData
Properties
absoluteSort?
optionalabsoluteSort?: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.
Inherited from
align?
optionalalign?:ColumnAlign
Inherited from
allowFormulas?
optionalallowFormulas?: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.
Inherited from
autoHeight?
optionalautoHeight?:boolean
Let this column's text WRAP, and let the row grow to fit it.
The row is measured after it renders and the measurement is fed back to the window engine, so the scrollbar and every row offset account for the real height. Two consequences worth knowing before turning it on:
• only RENDERED rows can be measured. Rows below the viewport are assumed to be the standard height until they scroll into it, so the scrollbar firms up as the user travels. Every virtualized grid that measures has this property; the alternative is laying out every row up front, which at a million rows is not an alternative. • measurements are dropped when a column is resized, because the width is what decided where the text wrapped.
When the height is known WITHOUT measuring, getRowHeight on the config is
both cheaper and exact.
band?
optionalband?: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.
Inherited from
bandShow?
optionalbandShow?:"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.
Inherited from
calculateSortValue?
optionalcalculateSortValue?: (row) =>unknown
Sort on a derived value (e.g. custom ordering) instead of the cell value.
Parameters
row
TRow
Returns
unknown
Inherited from
GridColumnDef.calculateSortValue
cellClassName?
optionalcellClassName?:string| ((ctx) =>string|undefined)
Extra class(es) on every cell of this column — a monospace SKU column, a
status tint. A function form allows per-VALUE classes without paying for a
full renderCell, which would replace the cell's content and lose the
built-in truncation and alignment.
chartRole?
optionalchartRole?:"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.
Inherited from
colSpan?
optionalcolSpan?: (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
Inherited from
comparator?
optionalcomparator?: (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
Inherited from
dataType?
optionaldataType?:GridDataType
Inherited from
dateFormat?
optionaldateFormat?: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.
Inherited from
editable?
optionaleditable?: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.
Inherited from
excelFormat?
optionalexcelFormat?: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.
Inherited from
exportLink?
optionalexportLink?: (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
Inherited from
field?
optionalfield?:string
Property read from the row object (dot paths NOT expanded — use valueGetter).
Inherited from
filterable?
optionalfilterable?:boolean
Inherited from
filterOperators?
optionalfilterOperators?: readonlyCustomFilterOperator<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.
Inherited from
flex?
optionalflex?: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.
Inherited from
formula?
optionalformula?: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.
Inherited from
groupable?
optionalgroupable?:boolean
Inherited from
groupEdit?
optionalgroupEdit?:"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.
Inherited from
groupInterval?
optionalgroupInterval?: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.
Inherited from
headerName?
optionalheaderName?:string
Inherited from
headerTooltip?
optionalheaderTooltip?:string
Tooltip for this column's HEADER cell.
hideBelow?
optionalhideBelow?: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.
Inherited from
hideInChooser?
optionalhideInChooser?: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.
Inherited from
id?
optionalid?:string
Stable identity; defaults to field. Required when two columns share a field.
Inherited from
lookup?
optionallookup?:ColumnLookup<TRow>
Value list for a code→label column. Drives the select editor, and (for a static list) the displayed text.
Inherited from
maxWidth?
optionalmaxWidth?:number
Inherited from
minWidth?
optionalminWidth?:number
Inherited from
numberFormat?
optionalnumberFormat?: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).
Inherited from
pin?
optionalpin?:ColumnPin
Inherited from
renderCell?
optionalrenderCell?: (ctx) =>ReactNode
Expensive escape hatch — renders arbitrary React per cell.
Parameters
ctx
CellRenderContext<TRow>
Returns
ReactNode
renderEditor?
optionalrenderEditor?: (ctx) =>ReactNode
Replace the built-in editor for this column (Enterprise). Use for controls the grid does not ship — a colour picker, a masked input, an autocomplete against your own API.
Parameters
ctx
EditorRenderContext<TRow>
Returns
ReactNode
renderFilter?
optionalrenderFilter?: (ctx) =>ReactNode
Replace this column's filter UI with your own — a range slider, a date
picker, a tag list. Drawn in the filter row's cell (surface: 'row')
when filterRow is on, and as the header popup's content
(surface: 'popup') when headerFilter is on; branch on surface to
draw each differently.
Call setValue with any filter for this column — a built-in condition,
a group, or one using a custom operator from filterOperators — or
null to clear. It goes through the same setColumnFilter the built-in
surfaces use, so the funnel, the filter panel and saved views see it.
Parameters
ctx
FilterRenderContext<TRow>
Returns
ReactNode
renderHeader?
optionalrenderHeader?: (ctx) =>ReactNode
Parameters
ctx
HeaderRenderContext<TRow>
Returns
ReactNode
renderTooltip?
optionalrenderTooltip?: (ctx) =>ReactNode
Rich tooltip content for this column's cells (P-TOOL-01): an image, a
small table, a link — anything React can draw. Wins over tooltip and
tooltipField; return null to show no tooltip for that cell. Runs only for
the cell the tooltip is about. Pair it with tooltip.interactive when the
content holds something to click.
Parameters
ctx
CellRenderContext<TRow>
Returns
ReactNode
reorderable?
optionalreorderable?:boolean
Inherited from
resizable?
optionalresizable?:boolean
Inherited from
sortable?
optionalsortable?:boolean
Inherited from
sortCycle?
optionalsortCycle?: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.
Inherited from
spanRows?
optionalspanRows?: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.
Inherited from
sparkline?
optionalsparkline?: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.
Inherited from
tooltip?
optionaltooltip?:string| ((ctx) =>string|null|undefined)
Tooltip text for this column's cells (P2.1).
Without it, a cell whose text does not fit still gets one — the grid falls back to showing the clipped text in full. Set this when the tooltip should say something the cell does NOT: a code's description, an abbreviation spelled out, why a value is flagged.
The function form runs only for the cell under the pointer, so it may be as expensive as it needs to be. Return null (or an empty string) to suppress the tooltip for that cell — including the truncation fallback.
tooltipField?
optionaltooltipField?:string
Read the tooltip from another FIELD of the row — the common case where the
long form already travels with the data (status / statusDetail).
tooltip wins if both are given.
valueFormatter?
optionalvalueFormatter?: (value,row) =>string
Display formatting hook (adapters render the returned string).
Parameters
value
unknown
row
TRow
Returns
string
Inherited from
valueGetter?
optionalvalueGetter?: (row) =>unknown
Derive the cell value; overrides field access.
Parameters
row
TRow
Returns
unknown
Inherited from
valueParser?
optionalvalueParser?: (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
Inherited from
valueSetter?
optionalvalueSetter?: (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
Inherited from
visible?
optionalvisible?:boolean
Inherited from
width?
optionalwidth?:number
Inherited from
wrapHeaderText?
optionalwrapHeaderText?: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.