Column definitions

Describe each column once, with a key, a header and a type, and the grid handles display, sorting, filtering and export.

A grid takes columns, an array of column definitions in display order. Each definition names the row field to read (key), the title to show (header), and a type that decides how the value is formatted, aligned, sorted and filtered. Everything else, such as width, pinning, tooltips and editing, is an optional field on the same object.

Sort a column from its header, hover a cut-off value for its tooltip, or drag a header edge to resize:

The shape of a column

<script lang="ts">
  import { Grid, type ColumnDef } from 'bo-grid';

  const columns: ColumnDef[] = [
    { type: 'text', key: 'symbol', header: 'Symbol', sub: 'name', width: 170 },
    { type: 'price', key: 'price', header: 'Price', width: 96 },
    { type: 'percent', key: 'change', header: 'Chg %', width: 90 },
    { type: 'volume', key: 'volume', header: 'Volume', width: 100 },
    { type: 'text', key: 'sector', header: 'Sector', flex: 1 },
  ];

  let rows = $state([
    { id: 1, symbol: 'VNM', name: 'Vinamilk', price: 68.5, change: 1.2, volume: 1_204_000, sector: 'Consumer' },
  ]);
</script>

<Grid {rows} {columns} height={400} />

• key is the row field the column reads. It is also the column’s identity: sorting, filtering, hiding and saved layouts refer to columns by key, so keep keys unique.
• header is the title in the header row.
• type picks the cell’s format and behaviour. ColumnDef is a union on type, so TypeScript checks each type’s own options (decimals on number, min and max on heatmap, currency on currency). See Column types for the full list.
• Rows are plain objects with a unique id: a number, or a string such as a symbol or UUID. If your data has another identity field, pass getRowId instead of copying it into id.

Widths

A column is either fixed or flexible:

• width sets a fixed width in pixels.
• flex sets a grow weight: flex columns share the width that fixed columns leave over, in proportion to their weights. A column with flex ignores width.
• minWidth and maxWidth bound what a drag-resize can do.

To make every column scale with the grid instead, set fitColumns on the grid. Column sizing covers resizing, fitColumns and autoWidth.

Alignment, classes and formatting

Number types line up on the right and the rest on the left. Set align to override that for one column, for example a custom column that holds numbers.

format(value, row) replaces the built-in formatter. It applies wherever the value is shown as text: the cell, its tooltip, copy and formatted export.

{ type: 'number', key: 'ratio', header: 'Ratio', format: (v) => `${Number(v).toFixed(1)}×` }

cellClass and headerClass add your own classes. cellClass can be a function of the value and the row. Rows render inside the grid, so target the classes with :global(...); see Row styles.

Defaults for every column

defaultColumn sets fields that every column starts from. A column’s own fields, and a registered cellType, win over it:

<Grid {rows} {columns} defaultColumn={{ tooltip: true, minWidth: 64, resizable: false }} height={480} />

To reuse a whole kind of column across grids, such as a money amount or an order status, register it once with cellTypes: see Registered cell types.

Locale

Built-in number, price, currency and date formatting uses en-US by default. Set the grid’s locale to change it for every column, or a column’s own locale to change one:

<Grid {rows} {columns} locale="vi-VN" height={480} />

Localization covers the grid’s own strings too.

Reference

{ type: 'custom', key: 'pnl', header: 'P&L', align: 'right' }

{ type: 'number', key: 'qty', header: 'Qty', format: (v) => Number(v).toLocaleString('vi-VN') }

{ type: 'price', key: 'last', header: 'Last', cellClass: (v, row) => (Number(v) >= Number(row.ceiling) ? 'at-ceiling' : undefined) }

const columns: ColumnDef[] = [
  { type: 'text', key: 'sym', header: 'Symbol', width: 90 },
  { type: 'price', key: 'last', header: 'Last', flash: 'auto' },
];

<Grid {rows} {columns} height={480} defaultColumn={{ minWidth: 72, sortable: false }} />

<Grid {rows} {columns} height={480} getRowId={(row) => `${row.account}:${row.sym}`} />