Header Renderers

Configure text, sortable, filterable, and custom headers.

Headers are configured through ColumnDef.header. A header can be a string or a HeaderConfig object.

String Headers

string-headers.ts
const columns: ColumnDef[] = [
  { field: 'name', header: 'Name', width: 220 },
  { field: 'email', header: 'Email', width: 260 },
];

Rich Headers

rich-headers.ts
const columns: ColumnDef[] = [
  {
    field: 'email',
    header: {
      text: 'Email',
      type: 'text',
      tooltip: { content: 'Primary contact email' },
      trailingIcon: { content: '@', position: 'trailing' },
    },
    width: 260,
  },
  {
    field: 'status',
    header: {
      text: 'Status',
      type: 'filterable',
      filterIndicator: { show: true, dropdownType: 'select' },
    },
    filterable: true,
    width: 140,
  },
];

Sortable Headers

sortable-header.ts
const columns: ColumnDef[] = [
  {
    field: 'price',
    header: {
      text: 'Price',
      type: 'sortable',
      sortIndicator: { show: true, ascIcon: '↑', descIcon: '↓' },
    },
    sortable: true,
    width: 120,
  },
];

Custom Header Renderers

When the built-in header types are not enough, implement a HeaderRenderer and reference it by name from the column’s header config. A renderer owns three methods — render (build the DOM once), update (react cheaply to state such as sort direction, hover, or width), and destroy (clean up).

custom-header.ts
class TwoLineHeaderRenderer implements HeaderRenderer {
  render(el, params) { /* build title + caption from params.config */ }
  update(el, params) { /* repaint from params.sortDirection */ }
  destroy(el) { el.replaceChildren(); }
}


grid.registerHeaderRenderer('two-line', new TwoLineHeaderRenderer());
// column: { sortable: true, header: { text: 'Salary', type: 'custom', renderer: 'two-line' } }

The grid handles the structural concerns for you:

  • Sizing — the header cell is sized to the column width before your renderer runs, so a renderer that only builds content will not collapse.
  • Sorting — on a sortable column, header clicks toggle sort automatically. If your renderer wires its own sort interaction, set handlesSortInteraction = true to opt out of the default handler.
  • Height — set headerHeight to give multi-line headers the vertical space they need (defaults to 40).

Header Events

header-events.ts
grid.on('header:click', ({ columnIndex, column }) => {
  console.log(columnIndex, column.field);
});


grid.on('header:sort:click', ({ columnIndex, nextDirection }) => {
  console.log(columnIndex, nextDirection);
});


grid.on('header:filter:click', ({ columnIndex, hasActiveFilter }) => {
  console.log(columnIndex, hasActiveFilter);
});
ℹ Info

Current public event names use colon-separated names such as header:click, header:sort:click, and header:filter:click.