Updating Initial Adaptable State

Summary

After go-live, you can still ship design-time updates without wiping the rest of User State
A numeric Revision (or UpdateStrategy: 'Override') replaces an entire section of State
Alternatively, UpdateStrategy: 'KeepUserDefined' refreshes design-time items while keeping user-created ones
Apply on next load, or at runtime via the State API — no grid remount required

Find Out More

For first-time setup see Providing Initial Adaptable State
See Adaptable State Persistence and the State Management Module for additional context

Why Update Initial State?

Initial Adaptable State is meant for first-time use: design-time objects are merged into User State once, then users change and persist their own configuration.

Later you often need to change those design-time defaults — a new Format Column, an updated Custom Sort, a ReadOnly flag — without clearing everything else the user has saved.

That is what the per-section Revision property is for.

Caution

Revision is not a substitute for first-time Initial State, nor a full wipe (reloadInitialState / Clear User State)
Nor is it a configuration that belongs in Adaptable Options rather than State

How Revision works

Every User State section implements BaseState, which includes:

Revision?: number | { Key: number; UpdateStrategy: 'Override' | 'KeepUserDefined' };

Key Rules:

Revision is per section (e.g. Format Column, Layout); bumping one section leaves other sections alone
Update runs only if new Revision Key (or numeric value) is higher than what's already stored in User State
On load (and when you call the runtime merge APIs below), AdapTable compares Initial State to persisted User State and applies any section whose Revision has increased.

Choosing a Strategy

The UpdateStrategy choice is between 'Override' or 'KeepUserDefined' and is as follows:

	Number / `Override`	`KeepUserDefined`
What happens to the section	Fully replaced by Initial State	Design-time items replaced; user-created items kept
User-created objects in that section	Lost	Kept
Best when	You want to reset that Module’s config from Initial State	Users may have added their own objects and you only want to refresh defaults
Typical shape	`Revision: 2` or `{ Key: 2, UpdateStrategy: 'Override' }`	`Revision: { Key: 2, UpdateStrategy: 'KeepUserDefined' }`

Hint

A plain number is shorthand for Override — replace only, no merging of user items

Replacing an entire section (Override)

Increment (or introduce) a numeric Revision on the section you want to replace.

AdapTable swaps that section in User State for the new Initial State contents.

Caution

A number is replace only — user-created items in that section are removed.

export default {
  CustomSort: {
    // Replaces the Custom Sort section in User State when Revision 2
    // is higher than the stored value. Other sections stay untouched.
    Revision: 2,
    CustomSorts: [
      {
        Name: 'CustomSort-Rating',
        ColumnId: 'Rating',
        SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
      },
    ],
  },
} as InitialState;

Revision — replace a whole section

Fork Fork

Starts with Format Column Revision 1 styling Name (blue)
Add User Format Column creates a runtime Format Column on Language (green)
Apply Revision 2 (Override) reloads with Initial State Format Column Revision 2 containing only Github Stars (yellow)
Because Revision is a number (Override), the whole Format Column section is replaced — the user Language style is removed
Other sections (e.g. Layout) are unchanged
Use Reset Demo to clear persisted state and start again

Try It Out

Confirm Name is blue
Click Add User Format Column — Language turns green
Click Apply Revision 2 (Override) — after reload, only Github Stars is styled (yellow); Name and user Language styles are gone
Click Reset Demo to restore Revision 1

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  FormatColumn,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';
import {initialStateRevision1, initialStateRevision2} from './initialState';

const ADAPTABLE_STATE_KEY = 'docs/RevisionOverrideDemo';
const PHASE_STORAGE_KEY = `${ADAPTABLE_STATE_KEY}/phase`;

const userFormatColumn: FormatColumn = {
  Name: 'formatColumn-language-user',
  Scope: {
    ColumnIds: ['language'],
  },
  Style: {
    BackColor: '#32cd32',
    ForeColor: 'Black',
    FontWeight: 'Bold',
  },
};

function getPhase(): '1' | '2' {
  if (typeof localStorage === 'undefined') {
    return '1';
  }
  return localStorage.getItem(PHASE_STORAGE_KEY) === '2' ? '2' : '1';
}

const phase = getPhase();

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Revision Override Demo',
  adaptableStateKey: ADAPTABLE_STATE_KEY,
  initialState: phase === '2' ? initialStateRevision2 : initialStateRevision1,
  dashboardOptions: {
    customToolbars: [
      {
        name: 'RevisionDemo',
        title: 'Revision',
        toolbarButtons: [
          {
            label: 'Add User Format Column',
            buttonStyle: {
              tone: 'neutral',
              variant: 'raised',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const formatColumnApi = context.adaptableApi.formatColumnApi;
              if (formatColumnApi.getFormatColumnByName(userFormatColumn.Name)) {
                context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                  'User Format Column already present on Language'
                );
                return;
              }
              formatColumnApi.addFormatColumn(userFormatColumn);
              // TODO(adaptable-patch): remove after patch (Format Column refresh + UpdateStrategy KeepUserDefined)
              context.adaptableApi.gridApi.refreshColumns(['language']);
              context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                'Added user Format Column on Language (green) — now Apply Revision 2'
              );
            },
          },
          {
            label: 'Apply Revision 2 (Override)',
            buttonStyle: {
              tone: 'info',
              variant: 'raised',
            },
            onClick: () => {
              localStorage.setItem(PHASE_STORAGE_KEY, '2');
              window.location.reload();
            },
          },
          {
            label: 'Reset Demo',
            buttonStyle: {
              tone: 'warning',
              variant: 'outlined',
            },
            onClick: () => {
              localStorage.removeItem(PHASE_STORAGE_KEY);
              localStorage.removeItem(ADAPTABLE_STATE_KEY);
              window.location.reload();
            },
          },
        ],
      },
    ],
  },
};

Read-only

Loading demo…

Keeping User-Created Items

For a more granular update, use the object form:

Key — bump whenever you ship a new version of that section
UpdateStrategy: 'KeepUserDefined' — replace items that came from Initial State; keep items users created at run-time

AdapTable tells them apart via each Adaptable Object’s Source property ('InitialState' vs 'User').

Note

Items with Source !== 'InitialState' are treated as user-defined and retained

This is the usual way to re-apply design-time objects on top of already persisted state — for example change a Format Column background, or mark it IsReadOnly.

Important

Re-include every Initial State item you still want (with any updated properties)
An omitted design-time item is dropped, even with KeepUserDefined
Only user-created items are preserved automatically

export default {
  CustomSort: {
    // Replaces design-time Custom Sorts; keeps any user-created ones
    Revision: {Key: 5, UpdateStrategy: 'KeepUserDefined'},
    CustomSorts: [
      {
        Name: 'CustomSort-Rating',
        ColumnId: 'Rating',
        SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
      },
    ],
  },
} as InitialState;

Revision — KeepUserDefined

Fork Fork

Starts with Format Column Revision 1 styling Name (blue)
Add User Format Column creates a runtime Format Column on Language (green)
Apply Revision 2 (KeepUserDefined) reloads with Initial State Format Column Revision: { Key: 2, UpdateStrategy: 'KeepUserDefined' } containing only Github Stars (yellow)
New Initial State item (Github Stars) is applied; user-created Language style is kept; old Initial State Name style is replaced
Use Reset Demo to clear persisted state and start again

Try It Out

Confirm Name is blue
Click Add User Format Column — Language turns green
Click Apply Revision 2 (KeepUserDefined) — after reload, Github Stars is yellow and user Language remains green (Name blue is gone)
Click Reset Demo to restore Revision 1

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  FormatColumn,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';
import {initialStateRevision1, initialStateRevision2} from './initialState';

const ADAPTABLE_STATE_KEY = 'docs/RevisionKeepUserDefinedDemo';
const PHASE_STORAGE_KEY = `${ADAPTABLE_STATE_KEY}/phase`;

const userFormatColumn: FormatColumn = {
  Name: 'formatColumn-language-user',
  Scope: {
    ColumnIds: ['language'],
  },
  Style: {
    BackColor: '#32cd32',
    ForeColor: 'Black',
    FontWeight: 'Bold',
  },
};

function getPhase(): '1' | '2' {
  if (typeof localStorage === 'undefined') {
    return '1';
  }
  return localStorage.getItem(PHASE_STORAGE_KEY) === '2' ? '2' : '1';
}

const phase = getPhase();

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Revision KeepUserDefined Demo',
  adaptableStateKey: ADAPTABLE_STATE_KEY,
  initialState: phase === '2' ? initialStateRevision2 : initialStateRevision1,
  dashboardOptions: {
    customToolbars: [
      {
        name: 'RevisionDemo',
        title: 'Revision',
        toolbarButtons: [
          {
            label: 'Add User Format Column',
            buttonStyle: {
              tone: 'neutral',
              variant: 'raised',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              const formatColumnApi = context.adaptableApi.formatColumnApi;
              if (formatColumnApi.getFormatColumnByName(userFormatColumn.Name)) {
                context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                  'User Format Column already present on Language'
                );
                return;
              }
              formatColumnApi.addFormatColumn(userFormatColumn);
              // TODO(adaptable-patch): remove after patch (Format Column refresh + UpdateStrategy KeepUserDefined)
              context.adaptableApi.gridApi.refreshColumns(['language']);
              context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                'Added user Format Column on Language (green) — now Apply Revision 2'
              );
            },
          },
          {
            label: 'Apply Revision 2 (KeepUserDefined)',
            buttonStyle: {
              tone: 'info',
              variant: 'raised',
            },
            onClick: () => {
              localStorage.setItem(PHASE_STORAGE_KEY, '2');
              window.location.reload();
            },
          },
          {
            label: 'Reset Demo',
            buttonStyle: {
              tone: 'warning',
              variant: 'outlined',
            },
            onClick: () => {
              localStorage.removeItem(PHASE_STORAGE_KEY);
              localStorage.removeItem(ADAPTABLE_STATE_KEY);
              window.location.reload();
            },
          },
        ],
      },
    ],
  },
};

Read-only

Loading demo…

Applying at runtime

Revision merges also run at startup.

To deploy a new Initial State (or re-sync) without remounting the grid, use State API functions:

API	What it does	Use when
`applyInitialState`	Merges Initial State into the current in-memory user state (same Revision rules). If you pass an argument, also updates `AdaptableOptions.initialState`.	You have new Initial State in hand and want to apply it now
`remergePersistedState`	Calls `StateOptions.loadState`, then merges with the current Initial State	Persistence changed elsewhere (or Initial State in options was updated) and you want to re-sync without a wipe
`reloadInitialState`	Clears persisted state and reloads from Initial State	You intentionally want a full wipe back to Initial State

Both applyInitialState and remergePersistedState persist afterward and refresh the grid / theme. Prefer them over remounting when shipping section Revisions at runtime.

Note

The State Management Module UI can also load Initial State from a JSON file
That replaces state from the file rather than applying a Revision merge

FAQ

Does bumping Revision wipe other Modules’ State? No. Only the section whose Revision increases is updated; every other section of User State is left alone.

What if the new Revision Key is not higher than the stored one? AdapTable ignores the update for that section. Always bump Key (or the numeric Revision) when you ship a new version.

Can I use { Key, UpdateStrategy: 'Override' } instead of a number? Yes. A plain number is equivalent to Override. Use the object form when you need KeepUserDefined, or when you want the strategy spelled out explicitly.

How does AdapTable know which items are “user-created”? Adaptable Objects carry a Source of 'InitialState' or 'User'. For KeepUserDefined, items whose Source is not 'InitialState' are kept and concatenated with the new Initial State.

PreviousPersisting AdapTable State NextManaging AdapTable State