ColumnConfig

Full column configuration including custom renderers, editors, and grouping metadata.

Extends BaseColumnConfig with additional features for customizing how cells are displayed and edited.

Example

const columns: ColumnConfig<Employee>[] = [
  // Basic sortable column
  { field: 'id', header: 'ID', width: 60, sortable: true },

  // Column with custom renderer
  {
    field: 'name',
    header: 'Employee',
    renderer: (ctx) => {
      const div = document.createElement('div');
      div.innerHTML = `<img src="${ctx.row.avatar}" /><span>${ctx.value}</span>`;
      return div;
    },
  },

  // Column with custom header
  {
    field: 'email',
    headerLabelRenderer: (ctx) => `${ctx.value} 📧`,
  },

  // Editable column (requires EditingPlugin)
  {
    field: 'status',
    editable: true,
    editor: (ctx) => {
      const select = document.createElement('select');
      // ... editor implementation
      return select;
    },
  },

  // Hidden column (can be shown via VisibilityPlugin)
  { field: 'internalNotes', hidden: true },
];

Properties

Property	Type	Description
`field`	`unknown` & `string`	Unique field key referencing property in row objects
`header?`	`string`	Visible header label; defaults to capitalized field
`type?`	`ColumnType`	Column data type.
`width?`	`string` \| `number`	Column width in pixels; fixed size (no flexibility)
`minWidth?`	`number`	Minimum column width in pixels (stretch mode only); when set, column uses minmax(minWidth, 1fr)
`sortable?`	`boolean`	Whether column can be sorted
`resizable?`	`boolean`	Whether column can be resized by user
`sortComparator?`	(a: `any`, b: `any`, rowA: `TRow`, rowB: `TRow`) => `number`	Optional custom comparator for sorting (a,b) -> number
`options?`	`object`[] \| () => `object`[]	For select type - available options
`multi?`	`boolean`	For select - allow multi select
`format?`	(value: `any`, row: `TRow`) => `string`	Formats the raw cell value into a display string.
`meta?`	`Record`<`string`, `unknown`>	Arbitrary extra metadata
`renderer?`	`ColumnViewRenderer`<`TRow`, `any`>	Optional custom cell renderer function. Alias for `viewRenderer`. Can return an HTMLElement, a Node, or an HTML string (which will be sanitized).
`viewRenderer?`	`ColumnViewRenderer`<`TRow`, `any`>	Optional custom view renderer used instead of default text rendering
`externalView?`	`object`	External view spec (lets host app mount any framework component)
`hidden?`	`boolean`	Whether the column is initially hidden
`lockVisible?`	`boolean`	Prevent this column from being hidden programmatically
`cellClass?`	(value: `unknown`, row: `TRow`, column: `ColumnConfig`<`TRow`>) => `string` \| `string`[]	Dynamic CSS class(es) for cells in this column. Called for each cell during rendering. Return class names to add to the cell element.
`headerLabelRenderer?`	`HeaderLabelRenderer`<`TRow`>	Custom header label renderer. Customize the label content while the grid handles sort icons, filter buttons, resize handles, and click interactions.
`headerRenderer?`	`HeaderRenderer`<`TRow`>	Custom header cell renderer. Complete control over the entire header cell. Resize handles are added automatically for resizable columns.
`editable?`	`boolean`	Whether the field is editable (enables editors). Requires EditingPlugin.
`editor?`	`ColumnEditorSpec`<`TRow`, `any`>	Optional custom editor factory or element tag name. Requires EditingPlugin.
`editorParams?`	`EditorParams`	Configuration parameters for built-in editors. Shape depends on column type (NumberEditorParams, TextEditorParams, DateEditorParams, SelectEditorParams). Requires EditingPlugin.
`nullable?`	`boolean`	Whether this column allows `null` values. Requires EditingPlugin.
`filterable?`	`boolean`	Whether this column can be filtered (only applicable when FilteringPlugin is enabled).
`filterParams?`	`FilterParams`	Configuration for the filter UI (only applicable when FilteringPlugin is enabled). For number columns: { min, max, step } For date columns: { min, max } (ISO date strings) Falls back to editorParams if not set.
`filterValue?`	(value: `unknown`, row: `any`) => `unknown`	Custom value extractor for filtering. Use this when the cell value is a complex type (e.g., an array of objects) and the filter should operate on derived primitive values instead.
`group?`	`string` \| `object`	Column group assignment for the GroupingColumnsPlugin. Columns with the same group.id are rendered under a shared header.
`pinned?`	`PinnedPosition`	Pin column to an edge of the grid.
`sticky?`	`PinnedPosition`	⚠️
`printHidden?`	`boolean`	Hide this column when printing (default: false). Use this to exclude interactive or less important columns from print output.

Property Details

type

Column data type.

Built-in types: 'string', 'number', 'date', 'boolean', 'select'

Custom types (e.g., 'currency', 'country') can have type-level defaults via gridConfig.typeDefaults or framework adapter registries.

Default: Inferred from first row data

format

Formats the raw cell value into a display string.

Used both for cell rendering and the built-in filter panel:

In cells, the formatted value replaces the raw value as text content.
In the filter panel (set filter), checkbox labels show the formatted value instead of the raw value, and search matches against the formatted text.

The row parameter is available during cell rendering but is undefined when called from the filter panel (standalone value formatting). Avoid accessing row properties in format functions intended for filter display.

// Currency formatter — works in both cells and filter panel
{
  field: 'price',
  format: (value) => `$${Number(value).toFixed(2)}`,
}

// ID-to-name lookup — filter panel shows names, not IDs
{
  field: 'departmentId',
  format: (value) => departmentMap.get(value as string) ?? String(value),
}

renderer

// Simple string template
renderer: (ctx) => `<span class="badge">${ctx.value}</span>`

// DOM element
renderer: (ctx) => {
  const el = document.createElement('span');
  el.textContent = ctx.value;
  return el;
}

cellClass

// Highlight negative values
cellClass: (value, row, column) => value < 0 ? ['negative', 'text-red'] : []

// Status-based styling
cellClass: (value) => [`status-${value}`]

// Single class as string
cellClass: (value) => value < 0 ? 'negative' : ''

headerLabelRenderer

Custom header label renderer. Customize the label content while the grid handles sort icons, filter buttons, resize handles, and click interactions.

Use this for simple customizations like adding icons, badges, or units.

// Add required field indicator
headerLabelRenderer: (ctx) => `${ctx.value} <span class="required">*</span>`

// Add unit to header
headerLabelRenderer: (ctx) => {
  const span = document.createElement('span');
  span.innerHTML = `${ctx.value}<br/><small>(kg)</small>`;
  return span;
}

headerRenderer

Custom header cell renderer. Complete control over the entire header cell. Resize handles are added automatically for resizable columns.

The context provides helper functions to include standard elements:

renderSortIcon() - Returns sort indicator element (null if not sortable)
renderFilterButton() - Returns filter button (null if not filterable)

Precedence: headerRenderer > headerLabelRenderer > header > field

headerRenderer: (ctx) => {
  const div = document.createElement('div');
  div.className = 'custom-header';
  div.innerHTML = `<span>${ctx.value}</span>`;
  const sortIcon = ctx.renderSortIcon();
  if (sortIcon) div.appendChild(sortIcon);
  return div;
}

editorParams

{ field: 'price', type: 'number', editable: true, editorParams: { min: 0, max: 1000, step: 0.01 } }

nullable

Whether this column allows null values. Requires EditingPlugin.

When true:

Text/number editors: clearing all content commits null.
Select editors: a “(Blank)” option is automatically prepended that commits null. The label defaults to "(Blank)" and can be overridden via SelectEditorParams.emptyLabel.
Date editors: clearing the date commits null.

When false:

Text editors: clearing commits "" (empty string).
Number editors: clearing commits editorParams.min if set, otherwise 0.
Select editors: no blank option is shown, forcing a selection.
Date editors: clearing commits editorParams.default if set, otherwise today’s date. The fallback preserves the original type (string → "YYYY-MM-DD", Date → new Date()).

When omitted (default), behaviour matches false for text/number columns and no special handling is applied.

Custom editors can read column.nullable from the ColumnEditorContext to implement their own nullable behaviour.

Default: false

columns: [
  { field: 'nickname', editable: true, nullable: true },
  { field: 'department', type: 'select', editable: true, nullable: true,
    options: [{ label: 'Engineering', value: 'eng' }, { label: 'Sales', value: 'sales' }] },
  { field: 'price', type: 'number', editable: true, nullable: false,
    editorParams: { min: 0 } }, // clears to 0
  { field: 'startDate', type: 'date', editable: true, nullable: false,
    editorParams: { default: '2024-01-01' } }, // clears to Jan 1 2024
]

filterable

Default: true

filterValue

Custom value extractor for filtering. Use this when the cell value is a complex type (e.g., an array of objects) and the filter should operate on derived primitive values instead.

The function receives the raw cell value and the full row, and should return either a single filterable value or an array of filterable values. When an array is returned, each element becomes an individual entry in the filter panel’s unique values list. During filtering:

notIn (set filter): row is hidden if ANY extracted value is in the excluded set
in (set filter): row passes if ANY extracted value is in the included set

// Array-of-objects column: extract individual names for filtering
{
  field: 'sellers',
  filterValue: (value) =>
    (value as { companyName: string }[])?.map(s => s.companyName) ?? [],
  format: (value) => (value as { companyName: string }[])?.map(s => s.companyName).join(', ') ?? '',
}

printHidden

columns: [
  { field: 'name', header: 'Name' },
  { field: 'actions', header: 'Actions', printHidden: true }, // Hidden in print
]