Column Groups (Spanning Headers) in Apex Grid

Apex Grid can render a spanning header row above the column headers, grouping related columns under a shared title. The columns array stays flat: grouping is purely a header-rendering concern, so column width, pinning, resizing, and reordering all keep working as before. Available on both <apex-grid> and <apex-grid-enterprise> since v3.3.

Defining groups

Declare the groups on the grid's columnGroups property, then point each column at a group by id with its group property:

grid.columns = [
  { key: 'first', headerText: 'First', group: 'name' },
  { key: 'last',  headerText: 'Last',  group: 'name' },
  { key: 'city',  headerText: 'City',  group: 'address' },
  { key: 'zip',   headerText: 'ZIP',   group: 'address' },
];

grid.columnGroups = [
  { id: 'name',    headerText: 'Name' },
  { id: 'address', headerText: 'Address' },
];

Membership is by reference: a column's group value matches a columnGroups entry's id. A spanning header cell renders above each group's columns, and ungrouped columns get a blank spacer above them.

Rules and constraints

• Members must be contiguous within one pin region (start / unpinned / end). A group whose members are split across non-adjacent positions warns and skips the spanning cell.
• Reordering is confined to the group. When column reordering is on, a grouped column can only move within its own group.
• The flat columns array is never mutated, so width, pinning, and resizing continue to work per column.

React example

import { useEffect, useRef } from 'react'
import 'apex-grid/define'

export default function GroupedHeaderGrid() {
  const ref = useRef<any>(null)

  useEffect(() => {
    const grid = ref.current
    grid.columns = [
      { key: 'first', headerText: 'First', group: 'name' },
      { key: 'last',  headerText: 'Last',  group: 'name' },
      { key: 'city',  headerText: 'City',  group: 'address' },
      { key: 'zip',   headerText: 'ZIP',   group: 'address' },
    ]
    grid.columnGroups = [
      { id: 'name',    headerText: 'Name' },
      { id: 'address', headerText: 'Address' },
    ]
    grid.data = data
  }, [])

  return <apex-grid ref={ref} style={{ height: 480 }} />
}