Column Definitions

Column Definitions (ColDef) define the structure and behavior of individual columns in your grid. Each column can be extensively customized for display, editing, filtering, and sorting.

Overview

Columns are defined using the columnDefs property in GridOptions:

import { ColDef } from 'ag-grid-community';

interface RowData {
  athlete: string;
  age: number;
  country: string;
}

const columnDefs: ColDef<RowData>[] = [
  { field: 'athlete', headerName: 'Athlete Name' },
  { field: 'age', filter: 'agNumberColumnFilter' },
  { field: 'country' }
];

Basic Column Properties

Identification

colId

string

Unique ID for the column. If not provided, defaults to field. Used in API methods to reference columns.

{ colId: 'athlete_id', field: 'athlete' }

field

string

The field of the row object to get data from. Supports dot notation for nested properties.

{ field: 'athlete' }
{ field: 'address.city' }  // Nested field

Display

headerName

string

The name to render in the column header. If not specified and field is set, the field name is used.

{ field: 'athlete', headerName: 'Athlete Name' }

headerValueGetter

string | HeaderValueGetterFunc

Function or expression to get the header value dynamically.

{
  headerValueGetter: (params) => {
    return params.location === 'csv' 
      ? 'Athlete (Export)' 
      : 'Athlete (Grid)';
  }
}

hide

boolean

default:"false"

Set to true to hide this column initially.

{ field: 'id', hide: true }

Width Configuration

Column Sizing Options

width

number

Initial width in pixels. Defaults to 200px if not specified.

{ field: 'athlete', width: 150 }

minWidth

number

Minimum width in pixels.

{ field: 'athlete', minWidth: 100 }

maxWidth

number

Maximum width in pixels.

{ field: 'description', maxWidth: 500 }

flex

number

Flex sizing similar to CSS flexbox. Columns with flex share available space proportionally.

{
  columnDefs: [
    { field: 'athlete', flex: 2 },  // Takes 2/3 of space
    { field: 'country', flex: 1 }   // Takes 1/3 of space
  ]
}

resizable

boolean

default:"true"

Enable/disable column resizing.

{ field: 'athlete', resizable: false }

Value Handling

Getting Values

valueGetter

string | ValueGetterFunc

Function or expression to get the cell value. Use instead of field for computed values.

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

valueFormatter

string | ValueFormatterFunc

Function to format values for display.

{
  field: 'price',
  valueFormatter: (params) => {
    return params.value != null ? `$${params.value.toFixed(2)}` : '';
  }
}

Setting Values

valueSetter

string | ValueSetterFunc

Function to set the cell value back into your data. Return true if data changed.

{
  field: 'athlete',
  valueSetter: (params) => {
    if (params.newValue !== params.oldValue) {
      params.data.athlete = params.newValue;
      return true;  // Data changed
    }
    return false;  // No change
  }
}

valueParser

string | ValueParserFunc

Function to parse user input for saving.

{
  field: 'age',
  valueParser: (params) => {
    return Number(params.newValue);
  }
}

Sorting

sortable

boolean

default:"true"

Enable/disable sorting for this column.

{ field: 'athlete', sortable: true }

sort

'asc' | 'desc' | SortDef

Initial sort direction.

{ field: 'age', sort: 'desc' }

sortIndex

number

When sorting by multiple columns, specifies the order.

[
  { field: 'country', sort: 'asc', sortIndex: 0 },
  { field: 'athlete', sort: 'asc', sortIndex: 1 }
]

comparator

SortComparatorFn

Custom sort comparator function.

{
  field: 'athlete',
  comparator: (valueA, valueB, nodeA, nodeB, isDescending) => {
    // Custom sorting logic
    return valueA.toLowerCase().localeCompare(valueB.toLowerCase());
  }
}

Filtering

filter

boolean | string | FilterDef

Enable filtering and specify the filter type.

{ field: 'age', filter: 'agNumberColumnFilter' }
{ field: 'athlete', filter: 'agTextColumnFilter' }
{ field: 'date', filter: 'agDateColumnFilter' }
{ field: 'country', filter: 'agSetColumnFilter' }  // Enterprise

filterParams

object

Parameters for the filter component.

{
  field: 'age',
  filter: 'agNumberColumnFilter',
  filterParams: {
    buttons: ['apply', 'reset'],
    closeOnApply: true
  }
}

floatingFilter

boolean

default:"false"

Show a floating filter for this column.

{ field: 'athlete', filter: true, floatingFilter: true }

Editing

editable

boolean | EditableCallback

default:"false"

Enable editing for this column. Can be a function for conditional editing.

// Always editable
{ field: 'athlete', editable: true }

// Conditionally editable
{
  field: 'age',
  editable: (params) => params.data.status === 'active'
}

cellEditor

string | Component

Specify the cell editor component.

{ field: 'age', cellEditor: 'agNumberCellEditor' }
{ field: 'country', cellEditor: 'agSelectCellEditor' }
{ field: 'notes', cellEditor: 'agLargeTextCellEditor' }

cellEditorParams

object

Parameters for the cell editor.

{
  field: 'country',
  cellEditor: 'agSelectCellEditor',
  cellEditorParams: {
    values: ['USA', 'UK', 'Canada', 'Australia']
  }
}

singleClickEdit

boolean

default:"false"

Start editing on single click instead of double click.

{ field: 'notes', editable: true, singleClickEdit: true }

Cell Rendering

cellRenderer

string | Component

Custom cell renderer component.

{
  field: 'status',
  cellRenderer: (params) => {
    const color = params.value === 'active' ? 'green' : 'red';
    return `<span style="color: ${color}">${params.value}</span>`;
  }
}

cellRendererParams

object

Parameters passed to the cell renderer.

{
  field: 'progress',
  cellRenderer: 'agSparklineCellRenderer',
  cellRendererParams: {
    sparklineOptions: {
      type: 'bar',
      fill: '#5470c6'
    }
  }
}

Styling

cellStyle

CellStyle | CellStyleFunc

CSS styles to apply to cells.

// Static style
{ field: 'athlete', cellStyle: { color: 'blue', fontWeight: 'bold' } }

// Dynamic style
{
  field: 'age',
  cellStyle: (params) => {
    if (params.value < 18) {
      return { backgroundColor: '#ffcccc' };
    }
    return null;
  }
}

cellClass

string | string[] | CellClassFunc

CSS classes to apply to cells.

{ field: 'athlete', cellClass: 'athlete-cell' }
{ field: 'status', cellClass: ['status-cell', 'highlighted'] }
{
  field: 'age',
  cellClass: (params) => params.value >= 18 ? 'adult' : 'minor'
}

cellClassRules

CellClassRules

Rules for applying CSS classes based on conditions.

{
  field: 'age',
  cellClassRules: {
    'age-warning': (params) => params.value < 18,
    'age-senior': (params) => params.value >= 65,
    'age-normal': (params) => params.value >= 18 && params.value < 65
  }
}

Pinning

pinned

'left' | 'right' | boolean

Pin column to left or right side of the grid.

{ field: 'athlete', pinned: 'left' }
{ field: 'actions', pinned: 'right' }

lockPinned

boolean

default:"false"

Prevent users from pinning/unpinning this column via UI.

{ field: 'athlete', pinned: 'left', lockPinned: true }

Column Types

Reuse column configurations with column types:

const gridOptions = {
  // Define reusable types
  columnTypes: {
    numberColumn: {
      filter: 'agNumberColumnFilter',
      cellClass: 'number-cell',
      valueFormatter: (params) => params.value?.toLocaleString()
    },
    dateColumn: {
      filter: 'agDateColumnFilter',
      valueFormatter: (params) => new Date(params.value).toLocaleDateString()
    }
  },
  
  // Use types in column definitions
  columnDefs: [
    { field: 'athlete' },
    { field: 'age', type: 'numberColumn' },
    { field: 'date', type: 'dateColumn' },
    { field: 'year', type: 'numberColumn' }
  ]
};

Column Groups

Group related columns together:

import { ColGroupDef } from 'ag-grid-community';

const columnDefs: (ColDef | ColGroupDef)[] = [
  {
    headerName: 'Athlete Details',
    children: [
      { field: 'athlete' },
      { field: 'age' },
      { field: 'country' }
    ]
  },
  {
    headerName: 'Results',
    children: [
      { field: 'year' },
      { field: 'sport' },
      { field: 'gold' },
      { field: 'silver' },
      { field: 'bronze' }
    ]
  }
];

Common Patterns

Before/After: Adding Computed Columns

const columnDefs = [
  { field: 'firstName' },
  { field: 'lastName' },
  { field: 'age' }
];

Before/After: Adding Custom Filtering

const columnDefs = [
  { field: 'athlete', filter: true },
  { field: 'age', filter: true }
];

Before/After: Adding Custom Cell Rendering

const columnDefs = [
  { field: 'status' },
  { field: 'progress' }
];

Type Safety

Use TypeScript for type-safe column definitions:

interface Athlete {
  athlete: string;
  age: number;
  country: string;
  year: number;
  gold: number;
  silver: number;
  bronze: number;
}

const columnDefs: ColDef<Athlete>[] = [
  { field: 'athlete' },  // TypeScript validates field names
  { field: 'age', type: 'number' },
  {
    headerName: 'Total Medals',
    valueGetter: (params) => {
      // params.data is typed as Athlete
      return params.data.gold + params.data.silver + params.data.bronze;
    }
  }
];

Best Practices

Use field names - Prefer field over valueGetter when possible for better performance
Leverage defaultColDef - Set common properties once in defaultColDef
Use column types - Create reusable column configurations for consistency
Provide colId - Essential for dynamically updating column definitions
Optimize value getters - Avoid expensive computations in valueGetter functions
Type your data - Use TypeScript generics for better IDE support

GridOptions - Configure the entire grid
Grid API - Column manipulation methods
Row Data - Understanding row data structure

Get Started

Framework Integration

Core Concepts

Features

Enterprise Features

Customization

Themes

Column Definitions

Overview

Basic Column Properties

Identification

Display

Width Configuration

Value Handling

Getting Values

Setting Values

Sorting

Filtering

Editing

Cell Rendering

Styling

Pinning

Column Types

Column Groups

Common Patterns

Before/After: Adding Computed Columns

Before/After: Adding Custom Filtering

Before/After: Adding Custom Cell Rendering

Type Safety

Best Practices

Get Started

Framework Integration

Core Concepts

Features

Enterprise Features

Customization

Themes

Documentation Index

​Overview

​Basic Column Properties

​Identification

​Display

​Width Configuration

​Value Handling

​Getting Values

​Setting Values

​Sorting

​Filtering

​Editing

​Cell Rendering

​Styling

​Pinning

​Column Types

​Column Groups

​Common Patterns

​Before/After: Adding Computed Columns

​Before/After: Adding Custom Filtering

​Before/After: Adding Custom Cell Rendering

​Type Safety

​Best Practices

​Related

Overview

Basic Column Properties

Identification

Display

Width Configuration

Value Handling

Getting Values

Setting Values

Sorting

Filtering

Editing

Cell Rendering

Styling

Pinning

Column Types

Column Groups

Common Patterns

Before/After: Adding Computed Columns

Before/After: Adding Custom Filtering

Before/After: Adding Custom Cell Rendering

Type Safety

Best Practices

Related