Apex Grid Column Header Customization

ApexGrid supports two ways to customize column headers: a plain text label via headerText, or a full Lit template via headerTemplate.

Customization via headerText

By default a column uses its key as the header label. Set headerText to display a more readable string.

{
  key: 'price',
  headerText: 'Price per item'
}

headerText is ignored when headerTemplate is provided. If both are set, only the template renders.

Customization via headerTemplate

headerTemplate accepts a function that returns a Lit TemplateResult. Import html from lit to write inline templates.

import { html } from 'lit'

{
  key: 'rating',
  headerTemplate: () => html`<h3>Rating</h3>`,
}

Sort button preservation

When headerTemplate is provided, the sort button is not removed. It still renders alongside your template content. The template replaces only the label area of the header cell, not the entire cell.

Example: icon and label

Use inline styles or a wrapper element to align an icon next to the label text.

import { html } from 'lit'

{
  key: 'revenue',
  sort: true,
  headerTemplate: () => html`
    <span style="display:flex;align-items:center;gap:4px;">
      <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">
        <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z"/>
      </svg>
      Revenue
    </span>
  `,
}

Example: native browser tooltip

Use the HTML title attribute to attach a tooltip without any additional dependencies.

import { html } from 'lit'

{
  key: 'churnRate',
  headerTemplate: () => html`
    <span title="Percentage of customers who cancelled in this period">
      Churn Rate
    </span>
  `,
}

Accessing column context

headerTemplate receives a context parameter of type ApexHeaderContext<T> containing { column, grid }. Use this when the template content needs to reflect properties of the column itself.

import { html } from 'lit'
import { ApexHeaderContext } from 'apex-grid'

interface Product {
  id: number
  name: string
  revenue: number
}

{
  key: 'revenue',
  sort: true,
  headerTemplate: (ctx: ApexHeaderContext<Product>) => html`
    <span title="Column key: ${ctx.column.key}">
      Revenue
    </span>
  `,
}

ctx.grid gives access to the grid instance if you need to read or modify grid state from inside the template.