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 { useCallback, useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
registerAllModules();
6

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

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

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

29
const COLUMNS = [
30
  { data: 'sku', type: 'text' },
31
  { data: 'name', type: 'text' },
32
  { data: 'category', type: 'text' },
33
  { data: 'price', type: 'numeric', numericFormat: { pattern: '0,0.00' } },
34
  { data: 'stock', type: 'numeric' },
35
  { data: 'status', type: 'text' },
36
];
37

38
function loadLayout() {
39
  try {
40
    const raw = localStorage.getItem(STORAGE_KEY);
41

42
    if (!raw) return null;
43
    const parsed = JSON.parse(raw);
44

45
    if (!Array.isArray(parsed.widths) || !Array.isArray(parsed.order)) return null;
46

47
    return parsed;
48
  } catch {
49
    return null;
50
  }
51
}
52

53
function saveLayout(widths, order) {
54
  localStorage.setItem(STORAGE_KEY, JSON.stringify({ widths, order }));
55
}
56

57
const saved = loadLayout();
58
const initialWidths = saved ? saved.widths : DEFAULT_COL_WIDTHS;
59
const initialOrder = saved ? saved.order : null;
60

61
const ExampleComponent = () => {
62
  const hotRef = useRef(null);
63

64
  const getCurrentOrder = useCallback(() => {
65
    const hot = hotRef.current?.hotInstance;
66

67
    if (!hot) return DEFAULT_COL_ORDER;
68
    const count = hot.countCols();
69
    const order = [];
70

71
    for (let i = 0; i < count; i++) {
72
      order.push(hot.toPhysicalColumn(i));
73
    }
74

75
    return order;
76
  }, []);
77

78
  const getCurrentWidths = useCallback(() => {
79
    const hot = hotRef.current?.hotInstance;
80

81
    if (!hot) return DEFAULT_COL_WIDTHS;
82
    const count = hot.countCols();
83
    const widths = [];
84

85
    for (let i = 0; i < count; i++) {
86
      widths.push(hot.getColWidth(i));
87
    }
88

89
    return widths;
90
  }, []);
91

92
  const handleAfterColumnResize = useCallback(() => {
93
    const hot = hotRef.current?.hotInstance;
94

95
    if (!hot) return;
96
    const widths = hot.getColHeader().map((_, visualIndex) => hot.getColWidth(visualIndex));
97

98
    saveLayout(widths, getCurrentOrder());
99
  }, [getCurrentOrder]);
100

101
  const handleAfterColumnMove = useCallback(
102
    (_movedColumns, _finalIndex, _dropIndex, _movePossible, movePerformed) => {
103
      if (!movePerformed) return;
104
      saveLayout(getCurrentWidths(), getCurrentOrder());
105
    },
106
    [getCurrentWidths, getCurrentOrder]
107
  );
108

109
  const handleReset = useCallback(() => {
110
    const hot = hotRef.current?.hotInstance;
111

112
    if (!hot) return;
113
    localStorage.removeItem(STORAGE_KEY);
114
    hot.columnIndexMapper.setIndexesSequence(DEFAULT_COL_ORDER);
115
    const resizePlugin = hot.getPlugin('manualColumnResize');
116

117
    DEFAULT_COL_WIDTHS.forEach((width, visualIndex) => {
118
      resizePlugin.setManualSize(visualIndex, width);
119
    });
120
    hot.render();
121
  }, []);
122

123
  return (
124
    <div>
125
      <div className="example-controls-container">
126
        <div className="controls">
127
          <button type="button" onClick={handleReset}>Reset layout</button>
128
        </div>
129
      </div>
130
      <HotTable
131
        ref={hotRef}
132
        data={data}
133
        colHeaders={['SKU', 'Name', 'Category', 'Price ($)', 'Stock', 'Status']}
134
        columns={COLUMNS}
135
        colWidths={initialWidths}
136
        manualColumnResize={true}
137
        manualColumnMove={initialOrder || true}
138
        rowHeaders={true}
139
        height={320}
140
        width="100%"
141
        autoWrapRow={true}
142
        licenseKey="non-commercial-and-evaluation"
143
        afterColumnResize={handleAfterColumnResize}
144
        afterColumnMove={handleAfterColumnMove}
145
      />
146
    </div>
147
  );
148
};
149

150
export default ExampleComponent;

1
import { useCallback, useRef } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import type { ColumnSettings } from 'handsontable/settings';
5

6
registerAllModules();
7

8
const STORAGE_KEY = 'ht-column-layout-v1';
9

10
/* start:skip-in-preview */
11
type ProductRow = {
12
  sku: string;
13
  name: string;
14
  category: string;
15
  price: number;
16
  stock: number;
17
  status: string;
18
};
19

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

36
const DEFAULT_COL_WIDTHS: number[] = [90, 200, 120, 90, 70, 110];
37
const DEFAULT_COL_ORDER: number[] = [0, 1, 2, 3, 4, 5];
38

39
const COLUMNS: ColumnSettings[] = [
40
  { data: 'sku', type: 'text' },
41
  { data: 'name', type: 'text' },
42
  { data: 'category', type: 'text' },
43
  { data: 'price', type: 'numeric', numericFormat: { pattern: '0,0.00' } },
44
  { data: 'stock', type: 'numeric' },
45
  { data: 'status', type: 'text' },
46
];
47

48
type SavedLayout = { widths: number[]; order: number[] };
49

50
function loadLayout(): SavedLayout | null {
51
  try {
52
    const raw = localStorage.getItem(STORAGE_KEY);
53

54
    if (!raw) return null;
55
    const parsed: unknown = JSON.parse(raw);
56

57
    if (
58
      typeof parsed !== 'object' ||
59
      parsed === null ||
60
      !Array.isArray((parsed as SavedLayout).widths) ||
61
      !Array.isArray((parsed as SavedLayout).order)
62
    ) {
63
      return null;
64
    }
65

66
    return parsed as SavedLayout;
67
  } catch {
68
    return null;
69
  }
70
}
71

72
function saveLayout(widths: number[], order: number[]): void {
73
  localStorage.setItem(STORAGE_KEY, JSON.stringify({ widths, order }));
74
}
75

76
const saved = loadLayout();
77
const initialWidths = saved ? saved.widths : DEFAULT_COL_WIDTHS;
78
const initialOrder = saved ? saved.order : null;
79

80
const ExampleComponent = () => {
81
  const hotRef = useRef<HotTableRef>(null);
82

83
  const getCurrentOrder = useCallback((): number[] => {
84
    const hot = hotRef.current?.hotInstance;
85

86
    if (!hot) return DEFAULT_COL_ORDER;
87
    const count = hot.countCols();
88
    const order: number[] = [];
89

90
    for (let i = 0; i < count; i++) {
91
      order.push(hot.toPhysicalColumn(i) as number);
92
    }
93

94
    return order;
95
  }, []);
96

97
  const getCurrentWidths = useCallback((): number[] => {
98
    const hot = hotRef.current?.hotInstance;
99

100
    if (!hot) return DEFAULT_COL_WIDTHS;
101
    const count = hot.countCols();
102
    const widths: number[] = [];
103

104
    for (let i = 0; i < count; i++) {
105
      widths.push(hot.getColWidth(i) as number);
106
    }
107

108
    return widths;
109
  }, []);
110

111
  const handleAfterColumnResize = useCallback(() => {
112
    const hot = hotRef.current?.hotInstance;
113

114
    if (!hot) return;
115
    const widths = (hot.getColHeader() as string[]).map((_, visualIndex) =>
116
      hot.getColWidth(visualIndex) as number
117
    );
118

119
    saveLayout(widths, getCurrentOrder());
120
  }, [getCurrentOrder]);
121

122
  const handleAfterColumnMove = useCallback(
123
    (
124
      _movedColumns: number[],
125
      _finalIndex: number,
126
      _dropIndex: number | undefined,
127
      _movePossible: boolean,
128
      movePerformed: boolean
129
    ) => {
130
      if (!movePerformed) return;
131
      saveLayout(getCurrentWidths(), getCurrentOrder());
132
    },
133
    [getCurrentWidths, getCurrentOrder]
134
  );
135

136
  const handleReset = useCallback(() => {
137
    const hot = hotRef.current?.hotInstance;
138

139
    if (!hot) return;
140
    localStorage.removeItem(STORAGE_KEY);
141
    hot.columnIndexMapper.setIndexesSequence(DEFAULT_COL_ORDER);
142
    const resizePlugin = hot.getPlugin('manualColumnResize');
143

144
    DEFAULT_COL_WIDTHS.forEach((width, visualIndex) => {
145
      resizePlugin.setManualSize(visualIndex, width);
146
    });
147
    hot.render();
148
  }, []);
149

150
  return (
151
    <div>
152
      <div className="example-controls-container">
153
        <div className="controls">
154
          <button type="button" onClick={handleReset}>Reset layout</button>
155
        </div>
156
      </div>
157
      <HotTable
158
        ref={hotRef}
159
        data={data}
160
        colHeaders={['SKU', 'Name', 'Category', 'Price ($)', 'Stock', 'Status']}
161
        columns={COLUMNS}
162
        colWidths={initialWidths}
163
        manualColumnResize={true}
164
        manualColumnMove={initialOrder || true}
165
        rowHeaders={true}
166
        height={320}
167
        width="100%"
168
        autoWrapRow={true}
169
        licenseKey="non-commercial-and-evaluation"
170
        afterColumnResize={handleAfterColumnResize}
171
        afterColumnMove={handleAfterColumnMove}
172
      />
173
    </div>
174
  );
175
};
176

177
export default ExampleComponent;

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.