Version 22.0 Developer Release Note

Summary

  • AdapTable 22 was released in March 2026 and supports AG Grid version 35.0
  • It contains many enhancements notably to the Adaptable User Interface

AdapTable 22.0 is a major version release.

The release contains a number of user-requested enhancements and improvements, including:

Breaking Change

  • There are a few significant Breaking Changes in AdapTable Version 22
    • AdapTable types are now imported from a single location (in place of 2 as previously)
    • The name of the root css file has changed from base.css to index.css
    • A few CSS variables have been added (and many more variables have been removed)
    • AdapTable objects in Initial State now require a Name property (which AdapTable autogenerates if missing)
    • The CellAlignment property has been moved into the Style object (and out of Format Column)

Upgrading with AI

  • The adaptable-upgrade Agent Skill can plan the move from AdapTable 21 to 22 for you: it checks the changes in this Release Note against your repository and writes a reviewable plan, which your coding agent then applies
  • Install the AdapTable Skills in your project with:
Terminal
npx skills add https://www.adaptabletools.com
  • Then ask your agent: "Use the adaptable-upgrade skill to plan the upgrade of this project to AdapTable 22", review the plan it writes, and ask it to apply the plan in a new session

Note

  • AdapTable 22 is the earliest version the Skill can upgrade to - applications on AdapTable 20 or earlier need to reach 21 first
  • The Skill can also plan the whole journey to a later major (e.g. 21 → 24) in one go
  • The Skill runs the adaptable CLI to migrate your initialState and validate the result against the target version; nothing else needs installing

Importing AdapTable Types

  • All AdapTable types are now imported from a single location (this was previously 2 separate locations)

Caution

  • The file location itself varies, based on which AdapTable framework version is being used
  • Each framework version requires different objects to be imported, so please read the relevant integration notes
Adaptable VariantFile locationDocs
Vanilla (TypeScript)@adaptabletools/adaptableAdapTable Vanilla Integration
React@adaptabletools/adaptable-react-aggridAdapTable React Installation
Angular@adaptabletools/adaptable-angular-aggridAdapTable Angular Integration
Vue@adaptabletools/adaptable-vue-aggridAdapTable Vue Integration

Angular Version

  • The minimum Angular Version now supported is 18

Note

This is in line with AG Grid which currently supports Angular Versions 18 to 21


Object Name Property

  • All AdapTable objects stored in Initial Adaptable State now contain a mandatory Name property

  • This allows developers easily to uniquely identify each object created (e.g. Format Column, or Alert etc.)

Hint

  • AdapTable's State Migration Wizard automatically generates a value for the Name property if one is missing
  • If required, the Name property can then be adjusted at run-time using the relevant UI wizard

Note

  • Objects like Layouts which already have a Name property have been left unchanged
  • Other objects, e.g. Calculated Columns, which have a FriendlyName property have also not been changed

Layout Changes


Other Changes


React Hooks

HookUsed to Access
useAdaptableStateThe whole of Adaptable State
useCurrentLayoutThe Current Layout - and there is also a setter function)
useAdaptableApiThe Adaptable API (or null if AdapTable is not yet ready).
  • The React Hooks are all imported and used in similar ways:
import {useAdaptableState, useCurrentLayout, useAdaptableApi} from '@adaptabletools/adaptable-react-aggrid';

const currentTheme = useAdaptableState(state => state.Theme.CurrentTheme);
const [layout, setCurrentLayout] = useCurrentLayout();
const api = useAdaptableApi();

UI Changes

  • AdapTable 22.0 contains signficant User Interface related changes

  • These are designed to improve the look and feel, themability and extensibility of the Adaptable UI

New index.css file

  • The key css class which you must import is index.css (in place of base.css as required previously)
  • The location of the index.css file varies, depending on which AdapTable framework version is being used:
Adaptable VariantOld fileNew file
Vanilla@adaptabletools/adaptable/base.css@adaptabletools/adaptable/index.css
React@adaptabletools/adaptable-react-aggrid/base.css@adaptabletools/adaptable-react-aggrid/index.css
Angular@adaptabletools/adaptable-angular-aggrid/base.css@adaptabletools/adaptable-angular-aggrid/index.css
Vue@adaptabletools/adaptable-vue-aggrid/base.css@adaptabletools/adaptable-vue-aggrid/index.css
  • You no longer need to import themes/light.css as this is now included in index.css
  • However, to use the dark theme, you still need to import themes/dark.css

Caution

The index.css file is always required if even if you only intend to use the dark theme

CSS layers

  • The AdapTable CSS is now nested into a CSS layer called adaptable

Find Out More

For more insight on CSS layers read this MDN page

  • If you don't use CSS layers, nothing is required, as layers have a lower precedence to global-scoped CSS

    Important

    • If you do use CSS layers, please ensure to put adaptable before your app layer
    • This will allow your application more easily to override Adaptable styles
    @layer adaptable, app, theme;

Note

Its now much easier to override default Adaptable styles, since the adaptable layer gives our css lower priority.

Previous to AdapTable 22, this rule didn't have the expected result:

.ab-Dialog__close-button {
  padding: 6px;
}

You had to make it stronger, either making the selector more complex:

.ab-Dialog__close-button.ab-Dialog__close-button {
  padding: 6px;
}

or by adding !important:

.ab-Dialog__close-button {
  padding: 6px !important;
}

Now the rule will work fine without anything else required.

Tailwind

  • Version 22 introduces a prefixed Tailwind build for our internal styling & classes
  • For non Tailwind users, nothing has changed or is different (as its purely for internal use)

Note

  • For existing Tailwind users this won't clash with your current styles or changes made in your Tailwind setup
  • This is because we use the twa: prefix, to avoid our class names colliding with other classes in your application

New CSS Variables

VariableDefault
--ab-cmp-file-droppable__transition—
--ab-cmp-floatingfilter-selected-options-text__font-weight—
--ab-cmp-simple-button__box-shadowMaterial-style elevation shadow
--ab-cmp-simple-button__hover-box-shadowElevated hover shadow
--ab-cmp-simple-button__transitionbox-shadow 0.28s cubic-bezier(0.4, 0, 0.2, 1)
--ab-color-accent-foreground#e2e2e2
--ab-color-primary-foregroundvar(--ab-color-text-on-primary)
--ab-color-shadowrgb(0 0 0 / 0.2)
--ab-focus-light__box-shadowaccentlight-based focus glow
--ab-input-height36px
--ab-popover-triangle-size—
--ab-shadow-mdMedium depth shadow
--ab-shadow-smSmall depth shadow

CSS Changes to Spacing

  • All CSS spacing is now derived from --ab-base-space: 4px using calc().
  • As a result 8 CSS spacing variables have been removed and are replaced with a calculation:
Old CSS VariableReplacementResulting Value
--ab-space-00px
--ab-space-1var(--ab-base-space)4px
--ab-space-2calc(var(--ab-base-space) * 2)8px
--ab-space-3calc(var(--ab-base-space) * 4)16px
--ab-space-4calc(var(--ab-base-space) * 8)32px
--ab-space-5calc(var(--ab-base-space) * 16)64px
--ab-space-6calc(var(--ab-base-space) * 32)128px
--ab-space-7calc(var(--ab-base-space) * 64)256px

Hint

It is simple to provide the new spacing using calc. For example, what was previously:

.mybox {
  padding: var(--ab-space-2);
  margin: var(--ab-space-3);
}

will now be replaced with:

.mybox {
  padding: calc(var(--ab-base-space) * 2);
  margin: calc(var(--ab-base-space) * 4);
}

Removed CSS Variables

  • Many CSS Variables (nearly 100) have been removed as they are no longer required
  • All the CSS Variables for these components have been removed:
    • Dialog
    • HelpBox
    • ErrorBox
    • WarningBox
    • CodeBlock
    • ListGroup / ListGroupItem
    • QuickFilter
    • OnePageWizard
    • ExpressionEditor
    • ModuleSelector
    • Misc
Deep Dive

Full list of CSS Variables which have been Removed


Upgrade Guide

Important

  • Everything below this point is the Upgrade Guide for taking a v.21 application to v.22
  • If you are new to AdapTable, or already on v.22, you can stop here

AdapTable 22 is a major version. The breaking surface is: AdapTable types import from the package root, the root stylesheet is renamed base.css → index.css with many CSS variables removed, Adaptable Objects in Initial State require a Name, and FormatColumn.CellAlignment moved into Style.

Some changes below shipped in a 21.x minor (21.1 or 21.2) rather than in 22.0; they are included because a project on 21.0 meets them on the way to 22. Each such row says so; projects already on that minor need nothing for it.

The upgrade has two elements:

  • Adaptable State — persisted State and initialState as it loads is migrated automatically: missing Names are generated and CellAlignment is moved into Style (see the Auto-migrated column in the Adaptable State table and State Migration)

  • Application source — packages, CSS, Adaptable Options, API calls, object types and initialState literals need to be updated by you; there are 2 paths:

Developer Guide

Upgrade Sequence

Whichever method you choose, the upgrade sequence is the same 2-step process:

1
Update packages and application source
2
Type-check, build and run

AdapTable State migrates on the first Grid load post upgrade.

Read the console: AdapTable logs the State objects it generated a Name for.


Upgrade with AI

Upgrading using the adaptable-upgrade Agent Skill is our recommended option (see Upgrading with AI above for installation).

The Skill reads every 21 → 22 change record — the tagged rows of the tables below — through the adaptable CLI, which searches your repository for each one, so the plan names the files and lines that change.

It writes a plan for your repository (ADAPTABLE_UPGRADE_SCOPE.md, ADAPTABLE_UPGRADE_CHANGES.md, ADAPTABLE_UPGRADE_STATE/) and your coding agent then applies it in a fresh session: package bumps, the CSS file and variable changes, the import rewrites, and meaningful Names in initialState.


Upgrade Manually

For those unwilling, or unable, to use AI agents there is an option to manually upgrade.

Developer Guide

Manual Steps to Upgrade

Work through the Breaking Changes tables in this order:

Hint

  • The v.21 column of each table is your search list
  • Find every hit in your code and replace it with the v.22 column
1
Packages & CSS

Upgrade Packages & CSS — AG Grid 35.0 first, then every @adaptabletools/* package to the same 22.x; point CSS imports at index.css and rewrite the removed CSS variables

2
Adaptable State

Update Adaptable State — State loads as-is (missing Names are generated, CellAlignment is moved, on every load), but add meaningful Names to the initialState literals so they compile and read well

3
Adaptable Options
4
Adaptable API
5
Adaptable Objects

Update any changed Adaptable Objects

6
Verify

Type-check, build and run

Deep Dive

Breaking Changes 21 → 22


State Migration

State Migration rewrites Adaptable State from the shape saved by v.21 to the shape v.22 expects, automatically wherever State loads:

  • every CustomSort, FlashingCellDefinition, FormatColumn, PlusMinusNudge, Shortcut and AlertDefinition without a Name is given a deterministic one (for example FormatColumn-<hash>)
  • FormatColumn.CellAlignment is moved into Style.Alignment

So a v.21 application runs unchanged; bring the initialState literals up to date when convenient — TypeScript literals without Name do not compile against the 22 types, and meaningful names read better than the generated ones.


Change Log

KeyTypeDescription
AT-3277Bug✅ Fix filtering for columns with valueGetters that implement toString()
AT-3276Enhancement✅ Add 'BeforeAdaptableStateChange' event
AT-3271Bug✅ Column Filter Resize handles are gone
AT-3263Bug✅ Percent Column cannot handle negative values
AT-3261Enhancement✅ Provide 'only' as aggregation function for Layouts
AT-3253Task✅ Add new UserInterface section to Adaptable State
AT-3242Task✅ Consolidate how adaptable types are imported
AT-3241Enhancement✅ Allow containers to be provided dynamically
AT-3238Task✅ Add API support to toggle visibility of all AdapTable UI controls
AT-3230Bug✅ Cannot edit Chart legend and title
AT-3229Enhancement✅ Improve keyboard navigation for Filters
AT-3225Bug✅ Issue when providing comma as decimal separator in Display Format
AT-3223Enhancement✅ Add Alignment to Adaptable Style object
AT-3217Enhancement✅ Add Name property to many Adaptable Objects
AT-3214Enhancement✅ Add GridApi method to manage multiple row changes in one transaction
AT-3210Enhancement✅ Store order of Pivot Result Columns in Layout
AT-3209Enhancement✅ Refactor Layout Editor
AT-3204Enhancement✅ Add functions to clone, share and set Extended Layouts
AT-3198Study✅ Improve Filtering performance
AT-3196Enhancement✅ Add `useAdaptableApi` hook to AdapTable React
AT-3195Enhancement✅ Add `useCurrentLayout` hook to AdapTable React
AT-3176Bug✅ ag-Grid-SelectionColumn [MISSING] appears when Row Grouping with row selection
AT-3174Task✅ Upgrade to Angular v18.x
AT-3173Task✅ Upgrade to AG Grid 35.0
AT-3169Enhancement✅ Dont display 'Add Note' Context Menu Item if more than one cell selected
AT-3167Enhancement✅ Visually Export also Pinned Columns, Cell Classes & Custom Header Styles
AT-3148Bug✅ Export of grouped columns with colId different than field fails
AT-3143Task✅ AdapTable UI: enhance, simplify and make more extendable
AT-3124Task✅ Add custom tracks in DevTools Chrome Profiler
AT-2841Task✅ Add "Command Buttons" in Action Columns
AT-2745Enhancement✅ Add `useAdaptableState` hook to AdapTable React