Persist and restore column widths and order

In this tutorial, you will save column widths and column order to localStorage as the user resizes or reorders columns. You will learn how to restore that layout on grid initialization so user preferences survive a page refresh.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
const STORAGE_KEY = 'ht-column-layout-v1';
7

8
/* start:skip-in-preview */
9
const data = [
10
  { sku: 'SKU-001', name: 'Wireless Keyboard', category: 'Electronics', price: 49.99, stock: 142, status: 'Active' },
11
  { sku: 'SKU-002', name: 'USB-C Hub', category: 'Electronics', price: 34.99, stock: 87, status: 'Active' },
12
  { sku: 'SKU-003', name: 'Ergonomic Chair', category: 'Furniture', price: 399.00, stock: 23, status: 'Active' },
13
  { sku: 'SKU-004', name: 'Monitor Stand', category: 'Furniture', price: 79.99, stock: 55, status: 'Active' },
14
  { sku: 'SKU-005', name: 'Noise-Cancelling Headphones', category: 'Electronics', price: 199.99, stock: 0, status: 'Out of Stock' },
15
  { sku: 'SKU-006', name: 'Mechanical Keyboard', category: 'Electronics', price: 129.99, stock: 34, status: 'Active' },
16
  { sku: 'SKU-007', name: 'Standing Desk', category: 'Furniture', price: 549.00, stock: 12, status: 'Active' },
17
  { sku: 'SKU-008', name: 'Webcam HD', category: 'Electronics', price: 89.99, stock: 61, status: 'Active' },
18
  { sku: 'SKU-009', name: 'Cable Organizer', category: 'Accessories', price: 14.99, stock: 203, status: 'Active' },
19
  { sku: 'SKU-010', name: 'Laptop Stand', category: 'Accessories', price: 29.99, stock: 0, status: 'Discontinued' },
20
  { sku: 'SKU-011', name: 'Blue Light Glasses', category: 'Accessories', price: 24.99, stock: 98, status: 'Active' },
21
  { sku: 'SKU-012', name: 'Desk Lamp', category: 'Furniture', price: 44.99, stock: 77, status: 'Active' },
22
];
23
/* end:skip-in-preview */
24

25
// Default column widths and order used when no saved layout exists.
26
const DEFAULT_COL_WIDTHS = [90, 200, 120, 90, 70, 110];
27
const DEFAULT_COL_ORDER = [0, 1, 2, 3, 4, 5];
28

29
/**
30
 * Reads the saved layout from localStorage.
31
 * Returns null when the key is absent, unparseable, or from an older schema.
32
 */
33
function loadLayout() {
34
  try {
35
    const raw = localStorage.getItem(STORAGE_KEY);
36

37
    if (!raw) return null;
38
    const parsed = JSON.parse(raw);
39

40
    // Guard against stale data that lacks expected keys.
41
    if (!Array.isArray(parsed.widths) || !Array.isArray(parsed.order)) return null;
42

43
    return parsed;
44
  } catch {
45
    return null;
46
  }
47
}
48

49
/** Persists column widths and order to localStorage. */
50
function saveLayout(widths, order) {
51
  localStorage.setItem(STORAGE_KEY, JSON.stringify({ widths, order }));
52
}
53

54
const saved = loadLayout();
55
const initialWidths = saved ? saved.widths : DEFAULT_COL_WIDTHS;
56
const initialOrder = saved ? saved.order : null;
57

58
const container = document.querySelector('#example1');
59

60
const hot = new Handsontable(container, {
61
  data,
62
  colHeaders: ['SKU', 'Name', 'Category', 'Price ($)', 'Stock', 'Status'],
63
  columns: [
64
    { data: 'sku', type: 'text' },
65
    { data: 'name', type: 'text' },
66
    { data: 'category', type: 'text' },
67
    { data: 'price', type: 'numeric', numericFormat: { pattern: '0,0.00' } },
68
    { data: 'stock', type: 'numeric' },
69
    { data: 'status', type: 'text' },
70
  ],
71
  colWidths: initialWidths,
72
  manualColumnResize: true,
73
  manualColumnMove: initialOrder || true,
74
  rowHeaders: true,
75
  height: 320,
76
  width: '100%',
77
  autoWrapRow: true,
78
  licenseKey: 'non-commercial-and-evaluation',
79

80
  // Capture the new width array after every column resize and persist it.
81
  afterColumnResize() {
82
    const widths = hot.getColHeader().map((_, visualIndex) =>
83
      hot.getColWidth(visualIndex)
84
    );
85

86
    saveLayout(widths, getCurrentOrder());
87
  },
88

89
  // Capture the new column order after every column move and persist it.
90
  afterColumnMove(_movedColumns, _finalIndex, _dropIndex, _movePossible, movePerformed) {
91
    if (!movePerformed) return;
92
    saveLayout(getCurrentWidths(), getCurrentOrder());
93
  },
94
});
95

96
/** Returns the current visual-to-physical column order as an array of physical indices. */
97
function getCurrentOrder() {
98
  const count = hot.countCols();
99
  const order = [];
100

101
  for (let visualIndex = 0; visualIndex < count; visualIndex++) {
102
    order.push(hot.toPhysicalColumn(visualIndex));
103
  }
104

105
  return order;
106
}
107

108
/** Returns the current column widths in visual order. */
109
function getCurrentWidths() {
110
  const count = hot.countCols();
111
  const widths = [];
112

113
  for (let visualIndex = 0; visualIndex < count; visualIndex++) {
114
    widths.push(hot.getColWidth(visualIndex));
115
  }
116

117
  return widths;
118
}
119

120
// Reset button: clear localStorage and restore the default layout.
121
document.querySelector('#reset-layout-btn').addEventListener('click', () => {
122
  localStorage.removeItem(STORAGE_KEY);
123

124
  // Reset column order to the identity sequence [0, 1, 2, 3, 4, 5].
125
  hot.columnIndexMapper.setIndexesSequence(DEFAULT_COL_ORDER);
126

127
  // Reset each column width through the ManualColumnResize plugin API.
128
  const resizePlugin = hot.getPlugin('manualColumnResize');
129

130
  DEFAULT_COL_WIDTHS.forEach((width, visualIndex) => {
131
    resizePlugin.setManualSize(visualIndex, width);
132
  });
133

134
  hot.render();
135
});

1
<div class="example-controls-container">
2
  <div class="controls">
3
    <button id="reset-layout-btn" type="button">Reset layout</button>
4
  </div>
5
</div>
6
<div id="example1"></div>

Overview

Difficulty: Beginner Time: ~20 minutes

This tutorial shows how to save column widths and column order to localStorage as the user resizes or reorders columns, then read those values back when the grid initializes. The result is a grid whose layout survives page refreshes.

What You’ll Build

A product-inventory grid with six columns (SKU, Name, Category, Price, Stock, Status) that:

Saves column widths to localStorage after every resize (afterColumnResize).
Saves column order to localStorage after every move (afterColumnMove).
Restores the saved layout when the page loads.
Falls back to default widths and order when no saved data exists, or when the stored data is malformed.
Provides a Reset layout button that clears the saved state and restores defaults via hot.updateSettings().

Before you begin

This recipe uses only built-in Handsontable features. No extra dependencies are required.

You should be familiar with:

Creating a basic Handsontable instance.
The manualColumnResize and manualColumnMove options.

Step 1 — Define defaults and a storage key

1
const STORAGE_KEY = 'ht-column-layout-v1';
2

3
const DEFAULT_COL_WIDTHS = [90, 200, 120, 90, 70, 110];
4
const DEFAULT_COL_ORDER = [0, 1, 2, 3, 4, 5];

What’s happening: STORAGE_KEY is a namespaced key used for every localStorage read and write in this recipe. Namespacing prevents collisions with other data stored by the same page.

DEFAULT_COL_WIDTHS lists the pixel width for each column in its default order. DEFAULT_COL_ORDER is an array of physical column indices — [0, 1, 2, 3, 4, 5] means the visual order matches the source order. Both are used when no saved layout exists and when the user clicks Reset layout.

Why include a version suffix (-v1) in the key? When you change the column count or column schema, old saved data becomes incompatible. Bumping the version suffix (-v2, -v3, …) means the next page load finds nothing under the new key, falls back to defaults, and starts fresh. Old data under the previous key is left to expire naturally.

Step 2 — Read and validate the saved layout

1
function loadLayout() {
2
  try {
3
    const raw = localStorage.getItem(STORAGE_KEY);
4

5
    if (!raw) return null;
6
    const parsed = JSON.parse(raw);
7

8
    if (!Array.isArray(parsed.widths) || !Array.isArray(parsed.order)) return null;
9

10
    return parsed;
11
  } catch {
12
    return null;
13
  }
14
}

What’s happening, step by step:

localStorage.getItem(STORAGE_KEY) returns null when the key does not exist. The function returns null immediately in that case.
JSON.parse() can throw when the stored string is not valid JSON — for example, when the browser truncated the write due to a storage quota error, or when an earlier version of the page stored plain text under the same key. The try/catch converts any parse error into a safe null return.
The Array.isArray() guards reject objects that look like JSON but are missing the expected widths and order keys — for example, data written by a different schema version.

Why not trust the stored data directly? localStorage is writable by any script on the page, and its contents can be manually edited in browser DevTools. Defensive validation ensures a corrupt entry does not break the grid initialization.

Step 3 — Write the saved layout

1
function saveLayout(widths, order) {
2
  localStorage.setItem(STORAGE_KEY, JSON.stringify({ widths, order }));
3
}

What’s happening: saveLayout serializes both arrays into a single JSON object and writes it under the storage key. Grouping them in one object means a single setItem call — localStorage operations are synchronous and blocking, so minimizing calls reduces the chance of a partial write.

Step 4 — Initialize Handsontable with the saved or default layout

1
const saved = loadLayout();
2
const initialWidths = saved ? saved.widths : DEFAULT_COL_WIDTHS;
3
const initialOrder = saved ? saved.order : null;
4

5
const hot = new Handsontable(container, {
6
  data,
7
  colHeaders: ['SKU', 'Name', 'Category', 'Price ($)', 'Stock', 'Status'],
8
  columns: [ /* ... */ ],
9
  colWidths: initialWidths,
10
  manualColumnResize: true,
11
  manualColumnMove: initialOrder || true,
12
  licenseKey: 'non-commercial-and-evaluation',
13
  /* hooks wired in the next step */
14
});

What’s happening:

colWidths: initialWidths sets the pixel widths for each column at startup. When initialWidths is the saved array, the columns start at exactly the sizes the user last saved.
manualColumnResize: true activates the resize handle on every column header border, so the user can drag to resize.
manualColumnMove: initialOrder || true deserves attention. When manualColumnMove receives an array of physical indices, Handsontable treats it as the initial visual-to-physical mapping and re-orders columns accordingly. When it receives true, columns start in their default order. Passing null or false would disable the feature entirely, so the fallback is true.

Why pass the order to manualColumnMove instead of using columnMapping? The manualColumnMove option is the documented way to specify an initial column order when the plugin is enabled. It reads the array once at initialization, sets up the column index mapper, and after that behaves exactly like manualColumnMove: true.

Step 5 — Capture and save column widths after a resize

1
afterColumnResize() {
2
  const widths = hot.getColHeader().map((_, visualIndex) =>
3
    hot.getColWidth(visualIndex)
4
  );
5

6
  saveLayout(widths, getCurrentOrder());
7
},

What’s happening:

afterColumnResize fires after the user finishes dragging a column border. At that point the column’s new width is already applied.
hot.getColHeader() returns the current column headers array. Its length equals the number of columns, so mapping over it produces an index from 0 to colCount - 1.
hot.getColWidth(visualIndex) returns the current pixel width for that visual column. Widths are read in visual order so the saved array aligns with the visual order at the time of saving.
getCurrentOrder() (defined in Step 6) reads the current visual order. Both are saved together so the two arrays always stay in sync.

Why save all widths, not just the resized one? If only the changed column’s width is stored, restoring requires knowing which column was last resized. Storing the full array keeps the saved state self-contained.

Step 6 — Capture and save column order after a move

1
afterColumnMove(_movedColumns, _finalIndex, _dropIndex, _movePossible, movePerformed) {
2
  if (!movePerformed) return;
3
  saveLayout(getCurrentWidths(), getCurrentOrder());
4
},

What’s happening:

afterColumnMove fires after the user drops a column in a new position. The fifth parameter, movePerformed, is false when the drop did not actually change the order (for example, the user dropped a column back in the same position). Checking it avoids an unnecessary localStorage write.
getCurrentOrder() and getCurrentWidths() read the current state at the moment the hook fires, so both values are always fresh.

The helper functions:

1
function getCurrentOrder() {
2
  const count = hot.countCols();
3
  const order = [];
4

5
  for (let visualIndex = 0; visualIndex < count; visualIndex++) {
6
    order.push(hot.toPhysicalColumn(visualIndex));
7
  }
8

9
  return order;
10
}
11

12
function getCurrentWidths() {
13
  const count = hot.countCols();
14
  const widths = [];
15

16
  for (let visualIndex = 0; visualIndex < count; visualIndex++) {
17
    widths.push(hot.getColWidth(visualIndex));
18
  }
19

20
  return widths;
21
}

hot.toPhysicalColumn(visualIndex) translates a visual index to the underlying physical index. Physical indices correspond to column positions in the original columns array and do not change when columns are reordered. Saving physical indices means the stored order can always be interpreted as “visual slot N holds column at physical index M”.

Why iterate instead of calling a bulk API? Handsontable does not expose a single method that returns the full visual-to-physical mapping array. The toPhysicalColumn loop is the idiomatic way to derive it.

Step 7 — Wire up the Reset layout button

1
document.querySelector('#reset-layout-btn').addEventListener('click', () => {
2
  localStorage.removeItem(STORAGE_KEY);
3

4
  // Reset column order to the identity sequence [0, 1, 2, 3, 4, 5].
5
  hot.columnIndexMapper.setIndexesSequence(DEFAULT_COL_ORDER);
6

7
  // Reset each column width through the ManualColumnResize plugin API.
8
  const resizePlugin = hot.getPlugin('manualColumnResize');
9

10
  DEFAULT_COL_WIDTHS.forEach((width, visualIndex) => {
11
    resizePlugin.setManualSize(visualIndex, width);
12
  });
13

14
  hot.render();
15
});

What’s happening:

localStorage.removeItem(STORAGE_KEY) deletes the saved entry so the next page load starts from defaults.
hot.columnIndexMapper.setIndexesSequence(DEFAULT_COL_ORDER) writes the identity sequence [0, 1, 2, 3, 4, 5] directly into the column index mapper, restoring the default visual order immediately without triggering additional moves.
resizePlugin.setManualSize(visualIndex, width) sets each column’s stored width in the ManualColumnResize plugin’s internal map. Because the sequence was reset first, visual and physical indices are in sync at this point.
hot.render() repaints the grid to reflect both changes at once.

Why not updateSettings({ colWidths, manualColumnMove })? updateSettings reapplies manualColumnMove by calling moveColumns(array, 0) on the current (already reordered) state — which does not reliably restore the identity sequence. Similarly, colWidths is a core option, not the ManualColumnResize plugin’s internal map, so passing it through updateSettings does not clear the widths the user has already set interactively. The direct plugin APIs bypass these limitations.

How It Works - Complete Flow

Page loads: loadLayout() reads and validates localStorage. If data exists, initialWidths and initialOrder are set from it. Otherwise they fall back to DEFAULT_COL_WIDTHS and null.
Grid initializes: colWidths sets pixel widths. manualColumnMove sets the visual order when an array is provided, or enables the feature with the default order when true.
User resizes a column: afterColumnResize fires, reads all column widths and the current order, and writes both to localStorage.
User moves a column: afterColumnMove fires (if movePerformed is true), reads all widths and the new order, and writes both to localStorage.
User refreshes the page: Step 1 repeats. The saved layout is found, and the grid initializes with the user’s preferred widths and order.
User clicks Reset layout: localStorage entry is removed. hot.columnIndexMapper.setIndexesSequence() restores default column order. resizePlugin.setManualSize() restores default widths per column. hot.render() repaints the grid. The next resize or move writes fresh data.

What you learned

Use colWidths to set initial column widths and manualColumnMove (with an array of physical indices) to set an initial visual order.
Read all column widths with hot.getColWidth(visualIndex) and translate visual positions to physical indices with hot.toPhysicalColumn(visualIndex).
Use afterColumnResize and afterColumnMove to detect when the user changes the layout and persist those changes immediately.
Validate data read from localStorage before using it, so malformed or stale entries fall back to defaults gracefully.
Call hot.columnIndexMapper.setIndexesSequence() and resizePlugin.setManualSize() to reset column order and widths at runtime without recreating the grid.

Next steps

Extend the recipe to also persist colHeaders label overrides or hidden column state.
If your page has multiple grids, give each grid its own storage key (e.g., ht-column-layout-v1-products, ht-column-layout-v1-orders).
Replace localStorage with a server-side API call to sync layout preferences across devices and browsers.
Combine this recipe with Build a dynamic column visibility toggle to let users both hide columns and remember their visibility state.