Data Grid Column Types and Formatting

Developer guide › Columns and cell rendering › Data Grid Column Types and Formatting

Types and formatting

A type is not a label. It is a bundle of behaviour: how a value is formatted, parsed back from text, compared when sorting, stored in the columnar backing, written to Excel, and put on the clipboard. Setting type configures all of that at once.

Units

A unit type stores a plain number in a named base unit and makes only display and input unit-aware. That is the whole design: the column still backs onto a typed array, so sorting, filtering, grouping and totalling stay ordinary arithmetic and never touch the rendered text. A gigabyte column holding 0.5 shows 512 MB, accepts 512M typed over it, and stores 0.5 throughout.

columns: [
  { field: 'span',     type: 'metres' },      // 1500 → "1.5 km"
  { field: 'load',     type: 'kilograms' },
  { field: 'inlet',    type: 'pressure' },     // 200000 → "200 kPa"
  { field: 'bearing',  type: 'degrees' },
  { field: 'cap',      type: 'capacitance' },  // 4.7e-11 → "47 pF"
  { field: 'inletTemp', type: 'celsius' },
],

// or configure your own base unit and precision
dataTypes: {
  runtime: createUnitType({ system: 'duration', unit: 'ms', display: 'auto' }),
}

Seventeen unit systems ship: data, bitrate, length, mass, duration, speed, acceleration, area, volume, energy, power, force, pressure, torque, density, flow and angle, plus fifteen SI-prefixed electrical and scientific quantities. registerUnitSystem adds one of your own.

significantFigures renders to a fixed precision rather than a fixed number of decimals. Two decimals is four significant figures at 12.34 kB and three at 1.54 kB, so a column claims different accuracy row by row depending on nothing but which unit auto picked; significant figures are what an instrument has, and they hold across the ladder. Rounding is applied before the unit is chosen, so 999,999 bytes to three figures is 1.00 MB rather than 1,000 kB.

const { formatUnit } = await import('../packages/core/src/index.js');

const spec = { system: 'data', unit: 'B', display: 'auto', locale: 'en-GB' };
return (`figures ${formatUnit(999999, { ...spec, significantFigures: 3 })}`
  + ` | none ${formatUnit(999999, spec)}`);

compound: ['ft', 'in'] renders one stored number across an ordered subset of the system's units - a length as 5 ft 11 in, a duration as 1 h 23 m. It is display and parse only: the stored value stays a single base-unit number, so sorting, filtering, grouping and totals are the same arithmetic as any other unit column. The units are sorted largest to smallest, the smallest carries the remainder, and parsing sums the parts, so the display round-trips through a paste. The mid-value editor - keystroke roll-over between feet and inches, caret behaviour at a rung boundary - is a separate, later piece of work; this is the read-and-paste half.

Types read from the data

A column that declares no type takes one from the rows. The first hundred non-empty values of that column are sampled, and a type is adopted only if every one of them matches it; anything mixed or ambiguous stays text and says so once on the console.

columns: [
  { field: 'sku' },                          // text
  { field: 'quantity' },                     // number: aligned right, numeric filter
  { field: 'shipped' },                      // date
  { field: 'expedited' }                     // boolean: checkbox editor
]

Sampling happens once, when rows first arrive. A grid built empty and filled later infers on that first load, so fetching after construction is no reason to declare types you would otherwise leave out. Later loads keep the types already settled on: data that arrives tomorrow cannot change a column's type under a formatter or an editor that was configured around it.

Only the built-in names are ever inferred. Candidates are tried in registration order, so every string reaches text and every number reaches number before an extended type is considered. A column of IP addresses or durations is text until you name the type you want.

Inference never overrules a decision you made. An explicit type, a preset that carries one, a type in columnDefaults, and a lookup all win; type: false turns sampling off and keeps the column text whatever it holds. Set sampleSize to sample more or fewer than a hundred.

Dates are stored as strings, deliberately

A date column stores '2024-03-11', not a Date. This is the single most consequential type decision in the product.

timestamp - an instant, stored UTC, shown in a chosen zone

type: 'timestamp' is the sibling to datetime for data that is one genuine moment everywhere - an audit time, an event created_at, a cross-region log line - rather than a wall clock.

Formats

format: 'currency:GBP:2'                     // £1,234.50
format: 'percent:1'                          // 87.4%
format: 'date:dd MMM yyyy'                   // 11 Mar 2024

format: {                                    // when the shorthand runs out
  type: 'number',
  style: 'currency', currency: 'GBP', decimals: 2,
  negative: 'parentheses',                   // (£1,234.50)
  negativeClass: 'is-loss',
  nullDisplay: ', ',
}

format: { decimals: 0, signed: true }        // +5, 0, -5

The shorthand grammar. A shorthand is style, or style:arg1:arg2 - colon-separated, every argument after the style optional. Seven styles are recognised, by their leading word: number:decimals ('number:0' → 1,235), percent:decimals ('percent:1' → 87.4%), currency:code:decimals ('currency:GBP:2' → £1,234.50; the code defaults to USD and decimals to the currency's own minor unit when omitted), date:pattern ('date:dd MMM yyyy'; everything after the first colon is the pattern, so a time pattern's own colons - 'date:HH:mm' - survive intact), relative (no argument: '3 days ago', re-rendering as the clock moves), boolean:trueLabel/falseLabel/nullLabel (slash-separated, not colon - 'boolean:Yes/No' or 'boolean:Yes/No/Unknown'), and text:transform:truncate ('text:upper:20'; transform is upper, lower or title). A string that does not start with one of these seven words is tried as an Excel-style mask ('£#,##0.00;(£#,##0.00)') and then as a bare date pattern ('dd MMM yyyy') before being rejected.

signed puts a leading + on a positive number, currency or percent value. Zero gets no sign either way - it is neither positive nor negative - and a negative value is entirely unaffected: it still renders however negative says ('minus' by default). Off by default, so an existing column's negatives-only look never changes underneath it.

A key in format that the resolved type does not read - a typo, or a key that belongs to a different format shape, such as signed written on a text column - is never silently dropped. It warns once, by column and key name, instead of doing nothing.

Lookups

A lookup column stores an id and shows a label. Sorting, filtering, grouping, copying and exporting all use the label, because that is the thing the user is reasoning about, but the data keeps the id.

{
  field: 'statusId',
  title: 'Status',
  type: 'lookup',
  lookup: { options: [
    { id: 1, label: 'Open' },
    { id: 2, label: 'Pending' },
    { id: 3, label: 'Closed' },
    { id: 4, label: 'Escalated', variant: 'danger' },
  ]},
  cell: { decoration: 'pill' },
}

Options may be a function, may return a promise, and may be searched remotely with an AbortSignal so a superseded keystroke cancels its own request.

Custom types

dataTypes: {
  reg32: LatticeGrid.createRadixType({
    radix: 2, bitWidth: 32, pad: true, signed: false, group: 8,
  }),
},
columns: [{ field: 'flags', type: 'reg32' }],

// 170 → 0b00000000 00000000 00000000 10101010