Saving and Restoring State

ApexGantt can capture where a user left off (zoom, scroll, collapsed rows, selection, sort, filter, manual column widths, and column order) as a serializable snapshot, then restore it later. You can persist it yourself through the API or let the chart save it to localStorage.

What the state captures

The snapshot is a GanttUiState object separate from the task data. Every field is optional on input to setState(), so a partial state applies just that slice and leaves the rest untouched.

FieldDescription
versionSchema version, set by getState()
zoomZoom level as pixels-per-day
scroll{ horizontal, vertical } pixel offsets
collapsedIDs of collapsed summary rows
selectedIDs of selected rows (requires enableSelection)
sortActive sort criteria; empty array means natural order
filterRulesActive structured filter, or null
quickFilterText in the quick-filter box
groupActive grouping { field, direction }, or null
columnWidthsManual per-column pixel widths
columnOrderUser-chosen column order

Grouping stores only field and direction; a custom accessor or label on the criterion is not persisted, so a restored grouping falls back to the column's own accessor.

Manual persistence with getState / setState

Capture the state and send it to your own backend, then restore it on the next load:

const saved = gantt.getState()   // JSON-serializable
// ... persist `saved` wherever you like ...

gantt.setState(saved)

Apply a partial state to change only one slice:

gantt.setState({ sort: [{ key: ColumnKey.Name, direction: 'asc' }] })

setState() re-renders once, then emits sortChange / filterChange for the parts that changed. Suppress those events with { silent: true }:

gantt.setState({ collapsed: ['phase-1'] }, { silent: true })

Automatic persistence with localStorage

Set persistState to have the chart restore on the first render() and save (debounced) on every view change. Pass true for the default key ('apexgantt-state'), or an object to set a custom key:

new ApexGantt(el, { series: tasks, persistState: true })
new ApexGantt(el, { series: tasks, persistState: { key: 'project-42-gantt' } })

A per-project key keeps multiple charts from overwriting each other. The snapshot is versioned and SSR-safe.

React example

import { ApexGanttChart } from 'react-apexgantt'
import type { GanttUserOptions } from 'react-apexgantt'

const options: Omit<GanttUserOptions, 'series'> = {
  persistState: { key: 'project-42-gantt' },
}

export default function PersistentGantt() {
  return <ApexGanttChart tasks={tasks} options={options} height="500px" />
}