Column Definitions

The ColumnDef<TData, TValue> interface defines how a column behaves, what data it displays, and what interactions it supports. Column definitions are passed via GridConfig.columns and can be updated at runtime via GridApi.setColumnDefs.

interface ColumnDef<TData = any, TValue = any> {
  colId?: string;
  field?: string & keyof TData;
  headerName?: string;
  width?: number;
  minWidth?: number;
  maxWidth?: number;
  flex?: number;
  resizable?: boolean;
  pinned?: PinnedPosition;
  lockPinned?: boolean;
  lockPosition?: boolean;
  hide?: boolean;
  suppressColumnsToolPanel?: boolean;
  sortable?: boolean;
  sort?: SortDirection;
  sortIndex?: number;
  comparator?: ColumnComparator<TData, TValue>;
  filterable?: boolean;
  filter?: string | boolean;
  filterParams?: Record<string, unknown>;
  floatingFilter?: boolean;
  editable?: boolean | ((params: CellCallbackParams<TData, TValue>) => boolean);
  cellEditor?: string;
  cellEditorParams?: Record<string, unknown>;
  cellRenderer?: CellRendererFn<TData, TValue>;
  cellClass?: string | string[] | ((params: CellCallbackParams) => string | string[]);
  cellStyle?: Record<string, string> | ((params: CellCallbackParams) => Record<string, string>);
  headerRenderer?: HeaderRendererFn<TData>;
  headerClass?: string | string[];
  valueGetter?: (params: ValueGetterParams<TData>) => TValue;
  valueSetter?: (params: ValueSetterParams<TData, TValue>) => boolean;
  valueFormatter?: (params: ValueFormatterParams<TData, TValue>) => string;
  valueParser?: (params: ValueParserParams<TData>) => TValue;
  aggFunc?: string | AggFunc<TValue>;
  allowedAggFuncs?: string[];
  rowGroup?: boolean;
  rowGroupIndex?: number;
  showRowGroup?: boolean;
  pivot?: boolean;
  pivotIndex?: number;
  children?: ColumnDef<TData>[];
  groupId?: string;
  marryChildren?: boolean;
  openByDefault?: boolean;
  tooltipField?: string;
  tooltipValueGetter?: (params: CellCallbackParams<TData, TValue>) => string;
  colSpan?: (params: CellCallbackParams<TData, TValue>) => number;
  rowSpan?: (params: CellCallbackParams<TData, TValue>) => number;
  dangerouslySetInnerHTML?: boolean;
}

Basic Properties

const columns: ColumnDef<Employee>[] = [
  { field: 'name', headerName: 'Full Name' },
  { colId: 'fullAddress', headerName: 'Address',
    valueGetter: ({ data }) => `${data?.street}, ${data?.city}` },
];

Display Properties

const columns: ColumnDef[] = [
  { field: 'name', flex: 2 },               // gets 2/3 of remaining space
  { field: 'age', flex: 1, minWidth: 80 },  // gets 1/3, min 80px
  { field: 'secret', hide: true },           // initially hidden
  { field: 'notes', width: 300, maxWidth: 500, resizable: true },
];

Sorting Properties

The ColumnComparator signature:

type ColumnComparator<TData, TValue> = (
  valueA: TValue,
  valueB: TValue,
  nodeA: RowNode<TData>,
  nodeB: RowNode<TData>,
  isDescending: boolean,
) => number;

const columns: ColumnDef[] = [
  { field: 'name', sortable: true, sort: 'asc', sortIndex: 0 },
  { field: 'salary', sortable: true, sort: 'desc', sortIndex: 1 },
  {
    field: 'startDate',
    sortable: true,
    comparator: (a, b) => new Date(a).getTime() - new Date(b).getTime(),
  },
];

Filtering Properties

const columns: ColumnDef[] = [
  { field: 'name', filterable: true, filter: true, floatingFilter: true },
  { field: 'status', filter: 'select', filterParams: { values: ['active', 'inactive'] } },
];

Editing Properties

const columns: ColumnDef<Employee>[] = [
  { field: 'name', editable: true },
  { field: 'salary', editable: true, cellEditor: 'number' },
  {
    field: 'department',
    editable: true,
    cellEditor: 'select',
    cellEditorParams: { values: ['Engineering', 'Sales', 'HR'] },
  },
  {
    field: 'notes',
    editable: (params) => params.data?.role === 'admin',
  },
];

Pinning Properties

const columns: ColumnDef[] = [
  { field: 'id', pinned: 'left', lockPinned: true, lockPosition: true, width: 80 },
  { field: 'name', pinned: 'left' },
  { field: 'actions', pinned: 'right', width: 100 },
];

Grouping Properties

const columns: ColumnDef[] = [
  { field: 'department', rowGroup: true, rowGroupIndex: 0 },
  { field: 'team', rowGroup: true, rowGroupIndex: 1 },
  { field: 'name', showRowGroup: true },
  { field: 'salary', aggFunc: 'sum' },
];

Aggregation Properties

const columns: ColumnDef[] = [
  { field: 'salary', aggFunc: 'sum' },
  { field: 'age', aggFunc: 'avg' },
  { field: 'name', aggFunc: 'count' },
  {
    field: 'rating',
    aggFunc: (values) => values.reduce((a, b) => a + b, 0) / values.length,
    allowedAggFuncs: ['sum', 'avg'],
  },
];

Value Pipeline

The value pipeline controls how data flows through a column:

data[field] or valueGetter --> valueFormatter --> cellRenderer --> display
user input --> valueParser --> valueSetter --> data[field]

valueGetter

{
  colId: 'fullName',
  headerName: 'Full Name',
  valueGetter: (params) => {
    return `${params.data?.firstName} ${params.data?.lastName}`;
  },
}

ValueGetterParams:

valueFormatter

{
  field: 'salary',
  valueFormatter: (params) => `$${params.value.toLocaleString()}`,
}

{
  field: 'startDate',
  valueFormatter: (params) =>
    new Date(params.value).toLocaleDateString('en-US'),
}

ValueFormatterParams:

cellRenderer

{
  field: 'status',
  cellRenderer: (params) => {
    const badge = document.createElement('span');
    badge.className = `status-badge status-${params.value}`;
    badge.textContent = params.value;
    return badge;
  },
}

// String return (requires dangerouslySetInnerHTML for HTML)
{
  field: 'progress',
  dangerouslySetInnerHTML: true,
  cellRenderer: (params) =>
    `<div class="progress-bar" style="width: ${params.value}%"></div>`,
}

valueParser

{
  field: 'salary',
  editable: true,
  cellEditor: 'text',
  valueParser: (params) => parseFloat(params.newValue.replace(/[,$]/g, '')),
}

ValueParserParams:

valueSetter

{
  colId: 'fullName',
  headerName: 'Full Name',
  valueGetter: (params) => `${params.data?.firstName} ${params.data?.lastName}`,
  valueSetter: (params) => {
    const [first, ...rest] = params.newValue.split(' ');
    params.data.firstName = first;
    params.data.lastName = rest.join(' ');
    return true;
  },
}

ValueSetterParams:

Rendering Properties

const columns: ColumnDef<Employee>[] = [
  {
    field: 'salary',
    cellClass: (params) => params.value > 100000 ? 'high-value' : 'normal',
    cellStyle: (params) => ({
      color: params.value > 100000 ? '#16a34a' : '#1e293b',
      fontWeight: params.value > 100000 ? 'bold' : 'normal',
    }),
  },
  {
    field: 'department',
    headerRenderer: (params) => {
      const el = document.createElement('div');
      el.textContent = params.displayName;
      el.className = 'custom-header';
      return el;
    },
    headerClass: 'department-header',
  },
];

Column Group Properties

const columns: ColumnDef[] = [
  { field: 'name' },
  {
    headerName: 'Contact',
    groupId: 'contact',
    marryChildren: true,
    children: [
      { field: 'email' },
      { field: 'phone' },
    ],
  },
  {
    headerName: 'Employment',
    groupId: 'employment',
    openByDefault: true,
    children: [
      { field: 'department' },
      { field: 'title' },
      { field: 'salary' },
    ],
  },
];

Tooltip Properties

const columns: ColumnDef[] = [
  { field: 'name', tooltipField: 'fullBio' },
  {
    field: 'status',
    tooltipValueGetter: (params) =>
      `Row ${params.node.id}: status is ${params.value}`,
  },
];

Spanning Properties

const columns: ColumnDef[] = [
  {
    field: 'name',
    colSpan: (params) => params.data?.isHeader ? 3 : 1,
  },
  {
    field: 'category',
    rowSpan: (params) => params.data?.categorySpan ?? 1,
  },
];

Pivot Properties

CellCallbackParams

Passed to cellClass, cellStyle, editable, tooltipValueGetter, colSpan, and rowSpan.

interface CellCallbackParams<TData, TValue> {
  data: TData | undefined;              // Row data (undefined for group rows)
  value: TValue;                        // Resolved cell value
  node: RowNode<TData>;                 // The row node
  colDef: ColumnDef<TData, TValue>;     // The column definition
  colId: string;                        // Column ID
  rowIndex: number;                     // Display index
}

ColumnState

The resolved internal column state, combining the original ColumnDef with runtime changes (resizing, reordering, etc.). Retrieved via GridApi.getColumnState() and restored via GridApi.applyColumnState().

Supporting Types

SortModelItem

interface SortModelItem {
  colId: string;          // Column identifier
  sort: 'asc' | 'desc';  // Sort direction
}

PinnedPosition

type PinnedPosition = 'left' | 'right' | null;

SortDirection

type SortDirection = 'asc' | 'desc' | null;

AggFunc

type AggFunc<TValue = any> = (values: TValue[]) => any;

CellRendererFn

type CellRendererFn<TData, TValue> = (
  params: CellCallbackParams<TData, TValue>,
) => string | HTMLElement;

HeaderRendererFn

type HeaderRendererFn<TData> = (params: {
  colDef: ColumnDef<TData>;
  colId: string;
  displayName: string;
  sortDirection: SortDirection;
  sortIndex: number | null;
}) => string | HTMLElement;