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:
- AdapTable's User Interface has been enhanced through introduction of Tailwind and CSS layers
- Layouts offer improved support for Extended Layouts and Pivot Result Columns
- Action Column Command Buttons added to Action Columns for frequent row based actions
- AdapTable React contains 3 new custom hooks
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.csstoindex.css - A few CSS variables have been added (and many more variables have been removed)
- AdapTable objects in Initial State now require a
Nameproperty (which AdapTable autogenerates if missing) - The
CellAlignmentproperty has been moved into the Style object (and out of Format Column)
Upgrading with AI
- The
adaptable-upgradeAgent 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:
- 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
initialStateand 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 Variant | File location | Docs |
|---|---|---|
| Vanilla (TypeScript) | @adaptabletools/adaptable | AdapTable Vanilla Integration |
| React | @adaptabletools/adaptable-react-aggrid | AdapTable React Installation |
| Angular | @adaptabletools/adaptable-angular-aggrid | AdapTable Angular Integration |
| Vue | @adaptabletools/adaptable-vue-aggrid | AdapTable 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
Nameproperty -
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
Nameproperty if one is missing - If required, the
Nameproperty can then be adjusted at run-time using the relevant UI wizard
Note
- Objects like Layouts which already have a
Nameproperty have been left unchanged - Other objects, e.g. Calculated Columns, which have a
FriendlyNameproperty have also not been changed
Layout Changes
- The Layout Editor has been enhanced so its easier to identify and update Column properties
- The order of (the dynamically created) Pivot Result Columns can now be stored in AdapTable State
- 3 new functions added to Layout API to set, clone and fetch Extended Layouts
- A new only aggregation function has been added, which will display in Grouped Layouts.
Other Changes
- Action Column Commands are now available in Action Columns; these are buttons designed to make it very straightforward to display Row Forms to create, clone, edit or delete rows
- Column Filtering performance has been substantially improved
Alignmenthas been added to the Adaptable Style object (was previously only in Format Column)- Containers can be provided using a function if required
- New User Interface API functions to enable toggling visibility of AdapTable UI (i.e. Dashboard, Tool Panel, Status Panels, Status Bar, Menus etc)
- New
manageGridDataGridApi function allows rows to be added, updated and deleted in a single transaction - Custom Tracks have been added to the DevTools Chrome Profiler
- A new Before AdapTable State Changes Event which fires before a change is made in AdapTable State
React Hooks
- AdapTable 22.0 provides 3 custom React hooks for users of AdapTable React:
Hint
The React Hooks can be used anywhere inside the
<Adaptable.Provider />component
| Hook | Used to Access |
|---|---|
useAdaptableState | The whole of Adaptable State |
useCurrentLayout | The Current Layout - and there is also a setter function) |
useAdaptableApi | The 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 ofbase.cssas required previously) - The location of the
index.cssfile varies, depending on which AdapTable framework version is being used:
| Adaptable Variant | Old file | New 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 |
Theme-related css files
- You no longer need to import
themes/light.cssas this is now included inindex.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
- 13 new CSS Variables have been added:
| Variable | Default |
|---|---|
--ab-cmp-file-droppable__transition | — |
--ab-cmp-floatingfilter-selected-options-text__font-weight | — |
--ab-cmp-simple-button__box-shadow | Material-style elevation shadow |
--ab-cmp-simple-button__hover-box-shadow | Elevated hover shadow |
--ab-cmp-simple-button__transition | box-shadow 0.28s cubic-bezier(0.4, 0, 0.2, 1) |
--ab-color-accent-foreground | #e2e2e2 |
--ab-color-primary-foreground | var(--ab-color-text-on-primary) |
--ab-color-shadow | rgb(0 0 0 / 0.2) |
--ab-focus-light__box-shadow | accentlight-based focus glow |
--ab-input-height | 36px |
--ab-popover-triangle-size | — |
--ab-shadow-md | Medium depth shadow |
--ab-shadow-sm | Small depth shadow |
CSS Changes to Spacing
- All CSS spacing is now derived from
--ab-base-space: 4pxusingcalc(). - As a result 8 CSS spacing variables have been removed and are replaced with a calculation:
| Old CSS Variable | Replacement | Resulting Value |
|---|---|---|
--ab-space-0 | 0px | |
--ab-space-1 | var(--ab-base-space) | 4px |
--ab-space-2 | calc(var(--ab-base-space) * 2) | 8px |
--ab-space-3 | calc(var(--ab-base-space) * 4) | 16px |
--ab-space-4 | calc(var(--ab-base-space) * 8) | 32px |
--ab-space-5 | calc(var(--ab-base-space) * 16) | 64px |
--ab-space-6 | calc(var(--ab-base-space) * 32) | 128px |
--ab-space-7 | calc(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
initialStateas it loads is migrated automatically: missingNames are generated andCellAlignmentis moved intoStyle(see theAuto-migratedcolumn in the Adaptable State table and State Migration) -
Application source — packages, CSS, Adaptable Options, API calls, object types and
initialStateliterals need to be updated by you; there are 2 paths:- Upgrade with AI (recommended): the
adaptable-upgradeSkill plans your code changes & your agent applies them - Upgrade Manually — run it yourself using the tables of changes below
- Upgrade with AI (recommended): the
Developer Guide
Upgrade Sequence
Whichever method you choose, the upgrade sequence is the same 2-step process:
Do this in one of 2 ways:
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
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
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
Update Adaptable Options
Update Adaptable API
Update any changed Adaptable Objects
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,ShortcutandAlertDefinitionwithout aNameis given a deterministic one (for exampleFormatColumn-<hash>) FormatColumn.CellAlignmentis moved intoStyle.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
| Key | Type | Description |
|---|---|---|
| AT-3277 | Bug | ✅ Fix filtering for columns with valueGetters that implement toString() |
| AT-3276 | Enhancement | ✅ Add 'BeforeAdaptableStateChange' event |
| AT-3271 | Bug | ✅ Column Filter Resize handles are gone |
| AT-3263 | Bug | ✅ Percent Column cannot handle negative values |
| AT-3261 | Enhancement | ✅ Provide 'only' as aggregation function for Layouts |
| AT-3253 | Task | ✅ Add new UserInterface section to Adaptable State |
| AT-3242 | Task | ✅ Consolidate how adaptable types are imported |
| AT-3241 | Enhancement | ✅ Allow containers to be provided dynamically |
| AT-3238 | Task | ✅ Add API support to toggle visibility of all AdapTable UI controls |
| AT-3230 | Bug | ✅ Cannot edit Chart legend and title |
| AT-3229 | Enhancement | ✅ Improve keyboard navigation for Filters |
| AT-3225 | Bug | ✅ Issue when providing comma as decimal separator in Display Format |
| AT-3223 | Enhancement | ✅ Add Alignment to Adaptable Style object |
| AT-3217 | Enhancement | ✅ Add Name property to many Adaptable Objects |
| AT-3214 | Enhancement | ✅ Add GridApi method to manage multiple row changes in one transaction |
| AT-3210 | Enhancement | ✅ Store order of Pivot Result Columns in Layout |
| AT-3209 | Enhancement | ✅ Refactor Layout Editor |
| AT-3204 | Enhancement | ✅ Add functions to clone, share and set Extended Layouts |
| AT-3198 | Study | ✅ Improve Filtering performance |
| AT-3196 | Enhancement | ✅ Add `useAdaptableApi` hook to AdapTable React |
| AT-3195 | Enhancement | ✅ Add `useCurrentLayout` hook to AdapTable React |
| AT-3176 | Bug | ✅ ag-Grid-SelectionColumn [MISSING] appears when Row Grouping with row selection |
| AT-3174 | Task | ✅ Upgrade to Angular v18.x |
| AT-3173 | Task | ✅ Upgrade to AG Grid 35.0 |
| AT-3169 | Enhancement | ✅ Dont display 'Add Note' Context Menu Item if more than one cell selected |
| AT-3167 | Enhancement | ✅ Visually Export also Pinned Columns, Cell Classes & Custom Header Styles |
| AT-3148 | Bug | ✅ Export of grouped columns with colId different than field fails |
| AT-3143 | Task | ✅ AdapTable UI: enhance, simplify and make more extendable |
| AT-3124 | Task | ✅ Add custom tracks in DevTools Chrome Profiler |
| AT-2841 | Task | ✅ Add "Command Buttons" in Action Columns |
| AT-2745 | Enhancement | ✅ Add `useAdaptableState` hook to AdapTable React |