Skip to content
ZenGrid

Column State

Enterprise

Introduction

Section titled “Introduction”

Column state is a serializable snapshot of the current layout — every column’s width, visibility, order, and pin position, plus the active sort and filter. Capture it to persist a user’s view (to localStorage or a backend) and apply it later to restore exactly what they had.

It’s an enterprise feature, driven by a ColumnStateManager. Build one from the grid; it reads and writes the grid’s column model, sort, and filter for you:

import { ColumnStateManager } from '@zengrid/enterprise';


const state = new ColumnStateManager(grid);


const snapshot = state.getState();
localStorage.setItem('grid-layout', JSON.stringify(snapshot));


// …later
state.applyState(JSON.parse(localStorage.getItem('grid-layout') ?? '{}'));

What’s captured

Section titled “What’s captured”

getState() returns a single ColumnLayoutState object — the columns in visual (left-to-right) order, plus the sort and filter:

interface ColumnLayoutState {
  columns: ColumnStateSnapshot[];  // one entry per column, in visual order
  sort?: SortState[];              // present when the sort plugin is installed
  filter?: FilterModel[];          // present when the filter plugin is installed
}


interface ColumnStateSnapshot {
  id?: string;
  field?: string;
  width?: number;
  visible?: boolean;
  order?: number;
  pinned?: 'left' | 'right' | null;
}

On the way back in, applyState(state, options) matches each column by id (falling back to field) and restores it. Order is rebuilt as a clean permutation, so a partial snapshot (a few columns) is safe — the columns you name move; the rest keep their relative position. Restore only part of the layout with the flags — all default to true:

state.applyState(saved, {
  applyWidth: true,
  applyVisibility: true,
  applyOrder: false,    // keep the current order
  applyPinned: true,
  applySort: true,
  applyFilter: false,   // leave the current filter alone
});

applyState also accepts a bare ColumnStateSnapshot[] array — handy for nudging a single column: state.applyState([{ field: 'region', visible: false }]).

Persisting pin position

Section titled “Persisting pin position”

Pin position round-trips too, but the frozen-column rendering is driven by a ColumnPinManager — so hand the same manager to the state manager and it captures/restores pins through it:

import { columnPinning, ColumnPinManager, ColumnStateManager } from '@zengrid/enterprise';


const pins = new ColumnPinManager();
const grid = new Zengrid(el, { colPinProvider: columnPinning(pins), columns });


const state = new ColumnStateManager(grid, { pins });

Auto-persist on every change

Section titled “Auto-persist on every change”

Rather than wiring a Save button, hand subscribe a callback and it fires after every tracked change — width, visibility, order, pin, sort, or filter — so you can stream the layout straight to storage. It returns an unsubscribe:

const stop = state.subscribe(() => {
  localStorage.setItem('grid-layout', JSON.stringify(state.getState()));
});


// later, when the grid is torn down
stop();

Try it live

Section titled “Try it live”

Change the layout with the buttons — widen a column, hide one, pin one, sort or filter — then Save, change it again, and Restore to snap it all back. The snapshot is a plain object you could just as easily send to a server.

Save the layout, then widen/hide/pin columns and hit Restore — width, visibility and pin all snap back to the saved snapshot.

Next

Section titled “Next”