AG Grid Migration Guide: Options, Events and API

Before you convert

Five minutes of preparation saves most of the surprises. Work through this before you rename anything.

1. Run ESLint's no-dupe-keys rule over your options objects. A key written twice in one object literal is legal JavaScript: the last one wins and the first is discarded before any grid is handed it. One real options object carried two getRowStyle definitions, and the shading rule in the first had never run once. No grid can warn about something it was never given, so this is the one check worth doing while the old configuration is still the live one.
2. Write down the options you actually use. Most configurations use a few dozen of the several hundred available. The table below is a name-for-name map for the ones that come up; anything missing from it usually has a name in the API reference, under the part of the grid it belongs to.
3. Decide where rows come from. Everything in the browser, a page at a time from an endpoint, blocks fetched as the reader scrolls with the query pushed to the server, or a live feed. The choice carries over one for one, and it is the decision that shapes everything else. See connecting your data.
4. Keep the console open on the first run. Every key, type, operator, column id and row key the grid does not recognise is named as it happens, so the work left to do is printed rather than hunted for.

How the pieces map

The shapes are close enough that most of a conversion is renaming, and the differences are worth knowing before you start.

Columns and defaults

columnDefs becomes columns and defaultColDef becomes columnDefaults, merged under every column before its own definition. Inside a column, the settings are grouped by what they affect: value for computing, formatting and parsing, cell for how it is drawn, edit, sort, filter, layout for width, pinning and visibility, and header for the heading. So a column that set eight flat properties sets the same eight, gathered into the part of the column each one is about.

A house configuration goes one level above that. defaults({ theme: 'navy', rowHeight: 32 }) is merged beneath the configuration of every grid built afterwards, so the look and the behaviour you want across an application are set once, in one place, rather than copied into every screen and drifting. The per-grid value always wins, so any grid can still say something different for itself. defaults() reads what is currently in force and defaults(null) clears it.

Rows and identity

rowData becomes rows and getRowId becomes rowKey, which takes a field name, a dot path, an array of fields for a composite key, or a function. Set it. Change tracking, streaming dedupe, selection that survives a reload and remote reloading all depend on the grid knowing which row is which.

Sizing columns

columns.fit() sizes the visible resizable columns so that together they exactly fill the viewport, and columns.autoSize() fits each column to what it is showing. Both have a declarative form: flex shares out spare width and is resolved first, and fit: 'content' keeps a column sized to its content as rows arrive, columns are shown, hidden, reordered or pinned, and the grid is resized.

Selection

One selection block holds the mode and the rest: checkbox for a generated column of row checkboxes, headerCheckbox for the select-all in its heading, checkboxOnly so a row whose click opens a record does not also select it, groupSelectsChildren, ranges and fillHandle. The checkbox column is generated rather than declared, so it is never exported and never appears in the tool panel.

Sorting, filtering and the external filter

Filters are one condition tree with a named operator per condition, whatever set them: a header popup, the filter row, the tool panel or your own code. Reading filters.get() always gives the whole truth. The external filter becomes a named predicate: filters.where(name, fn) registers it, and registering it is what makes it active, so there is no second flag to keep in step. Name the columns it reads in deps and the grid re-runs it only when one of those changes; call filters.reapply(name) when something it reads outside the grid changes, such as a rate table that has just arrived. Several predicates hold at once under their own names, and one marked pinned survives a clear-filters button, which is what a row-level permission wants.

Where rows come from

Everything resident in the browser is the default and needs no configuration. A server that paginates is source: { mode: 'paged', fetch }. A server that should do the work is mode: 'remote', which sends one published request carrying the range, sort, filters, quick text, grouping, pivot and totals, so your endpoint targets a documented shape. A pushdown adapter goes one step further and turns that request into what an engine already speaks, declaring what it can answer so the grid finishes only what is left over and tells you which part that was.

Events and saved views

There are no onX configuration properties. Every event goes through one bus, grid.on('cell:changed', handler), and on() returns its own unsubscribe. Every user-initiated change is gated by a cancellable before-event that can hold the action while a confirm dialog or a server check settles. A whole view, columns, order, filters, quick text, sort, grouping, pivot, expansion, selection, scroll and paging, is one serialisable object from state.get(); state.apply() restores it and reports anything it could not apply rather than failing quietly.

One configuration, converted

A support desk grid: seven columns, a computed cost, an editable priority, checkbox selection that does not fight the row click, paging, undo, a row style for a breached ticket, and an external filter behind a "my tickets" toggle. First as it was.

const rates = { low: 65, normal: 85, high: 120 };

const gridOptions = {
  columnDefs: [
    { field: 'id', headerName: 'Ticket', pinned: 'left', width: 110 },
    { field: 'customer', headerName: 'Customer', flex: 1, minWidth: 160,
      tooltip: (p) => p.data.customer + ' in ' + p.data.region },
    { field: 'region', headerName: 'Region', width: 120 },
    { field: 'opened', headerName: 'Opened', width: 130, filter: 'agDateColumnFilter' },
    { field: 'priority', headerName: 'Priority', width: 120, editable: true,
      cellEditor: 'agSelectCellEditor',
      cellEditorParams: { values: ['low', 'normal', 'high'] },
      cellClassRules: { 'is-high': (p) => p.value === 'high' } },
    { field: 'hours', headerName: 'Hours', width: 110, type: 'numericColumn',
      valueFormatter: (p) => (p.value == null ? '' : p.value.toFixed(1)) },
    { colId: 'cost', headerName: 'Cost', width: 130, type: 'numericColumn',
      valueGetter: (p) => p.data.hours * rates[p.data.priority],
      valueFormatter: (p) => gbp.format(p.value) },
  ],
  defaultColDef: { sortable: true, filter: true, resizable: true },
  rowData: tickets,
  getRowId: (p) => p.data.id,
  rowSelection: { mode: 'multiRow', checkboxes: true, headerCheckbox: true,
    enableClickSelection: false },
  pagination: true,
  paginationPageSize: 25,
  paginationPageSizeSelector: [25, 50, 100],
  undoRedoCellEditing: true,
  undoRedoCellEditingLimit: 20,
  getRowStyle: (p) => (p.data.breached ? { background: '#fff4f4' } : undefined),
  isExternalFilterPresent: () => onlyMine,
  doesExternalFilterPass: (node) => node.data.owner === me,
  onGridReady: (e) => e.api.sizeColumnsToFit(),
  onCellValueChanged: (e) => save(e.data),
  onSelectionChanged: (e) => updateToolbar(e.api.getSelectedRows()),
};

const api = agGrid.createGrid(document.getElementById('grid'), gridOptions);

// Elsewhere: the toggle that drives the external filter.
function toggleMine(on) {
  onlyMine = on;
  api.onFilterChanged();
}

And converted. The column settings gather into their sub-specs, the computed column declares what it reads so the grid knows when to work it out again, the external filter becomes a named predicate, and the handlers move onto the one bus.

<div id="grid" style="height: 420px"></div>

<script>
  const me = 'ana';
  const rates = { low: 65, normal: 85, high: 120 };
  const tickets = [
    { id: 'T-1001', customer: 'Northwind', region: 'EMEA', opened: '2026-09-02', priority: 'high',   hours: 6.5, owner: 'ana', breached: true },
    { id: 'T-1002', customer: 'Contoso',   region: 'EMEA', opened: '2026-09-03', priority: 'normal', hours: 2,   owner: 'bo',  breached: false },
    { id: 'T-1003', customer: 'Fabrikam',  region: 'AMER', opened: '2026-09-05', priority: 'low',    hours: 1.5, owner: 'ana', breached: false },
    { id: 'T-1004', customer: 'Tailspin',  region: 'APAC', opened: '2026-09-07', priority: 'high',   hours: 9,   owner: 'cai', breached: true },
  ];

  const grid = LatticeGrid.createGrid(document.getElementById('grid'), {
    rowKey: 'id',
    columnDefaults: { sort: true, filter: true, layout: { resizable: true } },
    columns: [
      { field: 'id', title: 'Ticket', layout: { pin: 'start', width: 110 } },
      { field: 'customer', title: 'Customer', layout: { flex: 1, min: 160 },
        cell: { tooltip: (p) => p.data.customer + ' in ' + p.data.region } },
      { field: 'region', title: 'Region', layout: { width: 120 } },
      { field: 'opened', title: 'Opened', type: 'date', layout: { width: 130 } },
      { field: 'priority', title: 'Priority', layout: { width: 120 },
        lookup: { options: ['low', 'normal', 'high'] },
        edit: { enabled: true, editor: 'select' },
        cell: { classWhen: { 'is-high': (p) => p.value === 'high' } } },
      { field: 'hours', title: 'Hours', type: 'number', format: { decimals: 1 },
        layout: { width: 110 } },
      { id: 'cost', title: 'Cost', type: 'number', layout: { width: 130 },
        format: { style: 'currency', currency: 'GBP' },
        value: { deps: ['hours', 'priority'], compute: (d) => d.hours * rates[d.priority] } },
    ],
    rows: tickets,
    selection: { mode: 'multiple', checkbox: true, headerCheckbox: true, checkboxOnly: true },
    pagination: { pageSize: 25, pageSizes: [25, 50, 100] },
    edit: { enabled: true, undoDepth: 20 },
    rowStyle: (p) => (p.data.breached ? { background: '#fff4f4' } : null),
  });

  // The external filter becomes a named predicate. Registering it is what makes
  // it present, and naming the columns it reads is what lets the grid re-run it
  // only when one of them changes on a row.
  grid.filters.where('myItems', (row) => row.owner === me, { deps: ['owner'] });

  // The toggle that used to call onFilterChanged() removes the predicate by name.
  function toggleMine(on) {
    grid.filters.where('myItems', on ? (row) => row.owner === me : null, { deps: ['owner'] });
  }

  grid.on('cell:changed', (e) => save(e.row.data));
  grid.on('selection:changed', () => updateToolbar(grid.selection.rows()));

  // sizeColumnsToFit() on first data, as one call once the grid is ready.
  grid.once('ready', () => grid.columns.fit());
</script>

Two things are worth pointing at. The cost column names hours and priority in deps, which is what lets the grid recompute that cell when either changes on a row and leave it alone otherwise. And the "my tickets" toggle no longer tells the grid that a filter changed: removing the predicate by name is the whole operation, because there was never a separate flag saying one was present.

The equivalence table

189 names, one row each: 154 that carry straight across, 26 that need a decision, 5 answered another way on purpose, and 4 with no equivalent. AG Grid names follow v36; where AG Grid renamed an option the older name is listed underneath, so an application on either version finds its row. Every Lattice Grid name here is one the shipped API reference documents.

The same table is machine-readable at /docs/migrate/from-ag-grid.json, if you would rather drive a codemod with it than read it.

What the grid tells you while you convert

Lattice Grid checks what it is handed and says so, by name, the moment it happens. Rejected input never becomes state: a key, a type, an operator or a sort entry the grid refuses is left out rather than half applied, so a saved view cannot carry the problem forward into the next session. Expect more console output than you are used to on the first run. That is the conversion telling you what is left to do, and it goes quiet as you work through it. Every one of these has a page of its own.

• An option the grid does not read. An option that came across from the old configuration and has no meaning here is ignored rather than guessed at, and the grid names it. That list, printed on your first run, is the shortest possible to-do list for the conversion. config.unknown:*
• A column key that configures nothing. The same on a column or a column group: the key is named, with the column it was on, so a setting that silently did nothing is visible on day one instead of in a support ticket. *.unknown:*
• A column type that does not exist. A type the grid does not carry falls back to text and says so. Worth acting on, because a text column sorts lexically and filters with text operators, which is rarely what a number or a date column wanted. type:*
• A filter operator a column cannot use. The condition is refused rather than admitted, so a filter the grid cannot honour never widens what a user can see. The warning names the operator it received and the operators that column accepts. In a compound filter only that leaf is dropped and every other condition still applies. filter:op:*:*
• A saved sort naming a column that has gone. Restoring a view written against an older column set drops the entry that no longer resolves, applies the rest, and reports it. A rejected entry never reaches the saved state, so the next save cannot carry the problem forward. grid.sort.unknown.*
• No stable row identity. Set rowKey to whatever getRowId used to return. Without it the grid identifies rows by object identity, which is enough to sort, filter and select within a session, and not enough for change tracking, streaming dedupe, selection that survives a reload, or a remote reload. rowKey.missing
• Two columns resolving to one id. A column id defaults to its field, so two columns reading the same field collide and the second is refused. Give one of them an explicit id and both come back. columns.duplicate:*

The full list is in every warning the grid prints, each with what it means, what the grid did about it, and what to change.

What does not translate, by design

Four things work differently here and will stay that way, so it is better to know them before you start than to find them halfway through.

• There is no free edition and no paid tier above it. AG Grid has a free community edition; we have nothing equivalent. What you get instead is one package with nothing held back: grouping, pivot, tree data, master detail, cell ranges, Excel export, charts, the board, the Gantt, KPI tiles, statistics and the AI layer are all in it, licensed per domain. See what it costs.
• Theming is CSS, not an API. Four themes ship, light, dark, high contrast and terminal, and everything past that is custom properties on the grid root. It covers a lot and it is not the same surface: AG Grid's theming API is the deeper of the two.
• The ecosystem around AG Grid is far larger. More answered questions, more third-party integrations, more people who have already hit your problem, and years more production history. Our answer to that is documentation and support, not a bigger crowd.
• A saved AG Grid state object does not load. The two grids describe a view differently, so plan to rebuild saved views rather than convert them: read the arrangement you want, save it with state.get(), and hand it back with state.apply().

When to stay on AG Grid

There are good reasons not to move, and they are easier to weigh now than after a week of renaming.

• The free edition already covers you. If your grid needs nothing beyond AG Grid's community features and cost is the deciding factor, stay: nothing here is cheaper than free.
• You rely on something this table marks as having no equivalent. Read those rows first. If the way round one of them does not suit your application, that is a real reason to wait.
• Your team's knowledge is the asset. A team fluent in one grid, with a support contract and a working build, is worth more than a tidier configuration. Convert when you want something on the other side, not for its own sake.

If you are weighing the two rather than converting, the AG Grid comparison puts them side by side on licensing, features and support.