Freeze and unfreeze columns at runtime

In this tutorial, you will freeze and unfreeze columns at runtime using external buttons. You will learn how to call hot.updateSettings with fixedColumnsStart and how frozen columns interact with manual column reordering.

1
import { useCallback, useRef, useState } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import './example1.css';
5

6
registerAllModules();
7

8
/* start:skip-in-preview */
9
const data = [
10
  { campaign: 'Spring Sale', channel: 'Email', impressions: 120000, clicks: 4800, conversions: 320, cpc: 0.42, revenue: 9600, roi: 2.28 },
11
  { campaign: 'Summer Push', channel: 'Paid Search', impressions: 85000, clicks: 3100, conversions: 210, cpc: 1.15, revenue: 6300, roi: 1.82 },
12
  { campaign: 'Back to School', channel: 'Social', impressions: 200000, clicks: 7200, conversions: 540, cpc: 0.31, revenue: 16200, roi: 3.10 },
13
  { campaign: 'Black Friday', channel: 'Display', impressions: 450000, clicks: 9000, conversions: 720, cpc: 0.65, revenue: 28800, roi: 2.94 },
14
  { campaign: 'Holiday Deals', channel: 'Email', impressions: 310000, clicks: 11200, conversions: 890, cpc: 0.28, revenue: 35600, roi: 4.12 },
15
  { campaign: 'New Year Offer', channel: 'Paid Search', impressions: 95000, clicks: 3800, conversions: 290, cpc: 1.22, revenue: 8700, roi: 1.65 },
16
  { campaign: 'Valentine Push', channel: 'Social', impressions: 140000, clicks: 5600, conversions: 410, cpc: 0.38, revenue: 12300, roi: 2.56 },
17
  { campaign: 'Spring Relaunch', channel: 'Display', impressions: 175000, clicks: 6300, conversions: 480, cpc: 0.55, revenue: 14400, roi: 2.18 },
18
];
19
/* end:skip-in-preview */
20

21
const colHeaders = ['Campaign', 'Channel', 'Impressions', 'Clicks', 'Conversions', 'CPC ($)', 'Revenue ($)', 'ROI'];
22

23
const columns = [
24
  { data: 'campaign', type: 'text' },
25
  { data: 'channel', type: 'text' },
26
  { data: 'impressions', type: 'numeric', numericFormat: { pattern: '0,0' } },
27
  { data: 'clicks', type: 'numeric', numericFormat: { pattern: '0,0' } },
28
  { data: 'conversions', type: 'numeric', numericFormat: { pattern: '0,0' } },
29
  { data: 'cpc', type: 'numeric', numericFormat: { pattern: '0.00' } },
30
  { data: 'revenue', type: 'numeric', numericFormat: { pattern: '$0,0' } },
31
  { data: 'roi', type: 'numeric', numericFormat: { pattern: '0.00' } },
32
];
33

34
const ExampleComponent = () => {
35
  const hotRef = useRef(null);
36
  const [frozenCount, setFrozenCount] = useState(0);
37

38
  const freezeUpTo = useCallback((n) => {
39
    const hot = hotRef.current?.hotInstance;
40
    const total = hot ? hot.countCols() : colHeaders.length;
41

42
    setFrozenCount(Math.min(n, total));
43
  }, []);
44

45
  const unfreezeAll = useCallback(() => {
46
    setFrozenCount(0);
47
  }, []);
48

49
  const statusText = frozenCount === 0
50
    ? 'No columns frozen'
51
    : `${frozenCount} column${frozenCount > 1 ? 's' : ''} frozen`;
52

53
  return (
54
    <div>
55
      <div className="freeze-controls">
56
        <div className="freeze-controls__freeze-btns">
57
          {colHeaders.map((header, index) => (
58
            <button
59
              key={header}
60
              type="button"
61
              onClick={() => freezeUpTo(index + 1)}
62
            >
63
              Freeze up to &quot;{header}&quot;
64
            </button>
65
          ))}
66
        </div>
67
        <div className="freeze-controls__footer">
68
          <button type="button" onClick={unfreezeAll}>Unfreeze all</button>
69
          <span className="freeze-controls__status">{statusText}</span>
70
        </div>
71
      </div>
72
      <HotTable
73
        ref={hotRef}
74
        data={data}
75
        colHeaders={colHeaders}
76
        columns={columns}
77
        fixedColumnsStart={frozenCount}
78
        manualColumnMove={true}
79
        rowHeaders={true}
80
        height="auto"
81
        width="100%"
82
        autoWrapRow={true}
83
        licenseKey="non-commercial-and-evaluation"
84
      />
85
    </div>
86
  );
87
};
88

89
export default ExampleComponent;

1
import { useCallback, useRef, useState } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import type { HotTableRef } from '@handsontable/react-wrapper';
5
import './example1.css';
6

7
registerAllModules();
8

9
/* start:skip-in-preview */
10
type CampaignRow = {
11
  campaign: string;
12
  channel: string;
13
  impressions: number;
14
  clicks: number;
15
  conversions: number;
16
  cpc: number;
17
  revenue: number;
18
  roi: number;
19
};
20

21
const data: CampaignRow[] = [
22
  { campaign: 'Spring Sale', channel: 'Email', impressions: 120000, clicks: 4800, conversions: 320, cpc: 0.42, revenue: 9600, roi: 2.28 },
23
  { campaign: 'Summer Push', channel: 'Paid Search', impressions: 85000, clicks: 3100, conversions: 210, cpc: 1.15, revenue: 6300, roi: 1.82 },
24
  { campaign: 'Back to School', channel: 'Social', impressions: 200000, clicks: 7200, conversions: 540, cpc: 0.31, revenue: 16200, roi: 3.10 },
25
  { campaign: 'Black Friday', channel: 'Display', impressions: 450000, clicks: 9000, conversions: 720, cpc: 0.65, revenue: 28800, roi: 2.94 },
26
  { campaign: 'Holiday Deals', channel: 'Email', impressions: 310000, clicks: 11200, conversions: 890, cpc: 0.28, revenue: 35600, roi: 4.12 },
27
  { campaign: 'New Year Offer', channel: 'Paid Search', impressions: 95000, clicks: 3800, conversions: 290, cpc: 1.22, revenue: 8700, roi: 1.65 },
28
  { campaign: 'Valentine Push', channel: 'Social', impressions: 140000, clicks: 5600, conversions: 410, cpc: 0.38, revenue: 12300, roi: 2.56 },
29
  { campaign: 'Spring Relaunch', channel: 'Display', impressions: 175000, clicks: 6300, conversions: 480, cpc: 0.55, revenue: 14400, roi: 2.18 },
30
];
31
/* end:skip-in-preview */
32

33
const colHeaders = ['Campaign', 'Channel', 'Impressions', 'Clicks', 'Conversions', 'CPC ($)', 'Revenue ($)', 'ROI'];
34

35
const columns = [
36
  { data: 'campaign', type: 'text' as const },
37
  { data: 'channel', type: 'text' as const },
38
  { data: 'impressions', type: 'numeric' as const, numericFormat: { pattern: '0,0' } },
39
  { data: 'clicks', type: 'numeric' as const, numericFormat: { pattern: '0,0' } },
40
  { data: 'conversions', type: 'numeric' as const, numericFormat: { pattern: '0,0' } },
41
  { data: 'cpc', type: 'numeric' as const, numericFormat: { pattern: '0.00' } },
42
  { data: 'revenue', type: 'numeric' as const, numericFormat: { pattern: '$0,0' } },
43
  { data: 'roi', type: 'numeric' as const, numericFormat: { pattern: '0.00' } },
44
];
45

46
const ExampleComponent = () => {
47
  const hotRef = useRef<HotTableRef>(null);
48
  const [frozenCount, setFrozenCount] = useState(0);
49

50
  const freezeUpTo = useCallback((n: number) => {
51
    const hot = hotRef.current?.hotInstance;
52
    const total = hot ? hot.countCols() : colHeaders.length;
53

54
    setFrozenCount(Math.min(n, total));
55
  }, []);
56

57
  const unfreezeAll = useCallback(() => {
58
    setFrozenCount(0);
59
  }, []);
60

61
  const statusText = frozenCount === 0
62
    ? 'No columns frozen'
63
    : `${frozenCount} column${frozenCount > 1 ? 's' : ''} frozen`;
64

65
  return (
66
    <div>
67
      <div className="freeze-controls">
68
        <div className="freeze-controls__freeze-btns">
69
          {colHeaders.map((header, index) => (
70
            <button
71
              key={header}
72
              type="button"
73
              onClick={() => freezeUpTo(index + 1)}
74
            >
75
              Freeze up to &quot;{header}&quot;
76
            </button>
77
          ))}
78
        </div>
79
        <div className="freeze-controls__footer">
80
          <button type="button" onClick={unfreezeAll}>Unfreeze all</button>
81
          <span className="freeze-controls__status">{statusText}</span>
82
        </div>
83
      </div>
84
      <HotTable
85
        ref={hotRef}
86
        data={data}
87
        colHeaders={colHeaders}
88
        columns={columns}
89
        fixedColumnsStart={frozenCount}
90
        manualColumnMove={true}
91
        rowHeaders={true}
92
        height="auto"
93
        width="100%"
94
        autoWrapRow={true}
95
        licenseKey="non-commercial-and-evaluation"
96
      />
97
    </div>
98
  );
99
};
100

101
export default ExampleComponent;

1
.freeze-controls {
2
  display: flex;
3
  flex-direction: column;
4
  gap: 6px;
5
  margin-bottom: 8px;
6
}
7

8
.freeze-controls__freeze-btns {
9
  display: flex;
10
  flex-wrap: wrap;
11
  gap: 6px;
12
}
13

14
.freeze-controls__footer {
15
  display: flex;
16
  align-items: center;
17
  gap: 8px;
18
}
19

20
.freeze-controls button {
21
  border: 1px solid var(--sl-color-gray-5);
22
  background: var(--sl-color-bg-nav);
23
  color: var(--sl-color-text);
24
  font-size: var(--sl-text-sm);
25
  line-height: 1.2;
26
  padding: 0.4rem 0.75rem;
27
  border-radius: 0;
28
  cursor: pointer;
29
  transition: color 0.15s, background-color 0.15s, border-color 0.15s;
30
}
31

32
.freeze-controls button:hover {
33
  color: var(--sl-color-white);
34
  background: var(--sl-color-gray-6);
35
}
36

37
.freeze-controls button:focus-visible {
38
  outline: 1px solid var(--sl-color-accent);
39
  outline-offset: 1px;
40
}
41

42
.freeze-controls__status {
43
  font-size: var(--sl-text-sm);
44
  font-style: italic;
45
  color: var(--sl-color-gray-2);
46
}

Overview

Difficulty: Beginner Time: ~15 minutes

This recipe shows how to freeze and unfreeze columns at runtime using hot.updateSettings({ fixedColumnsStart: n }). Frozen columns stay pinned to the left edge of the grid while the rest scroll horizontally. External buttons let users control the freeze boundary without touching the grid configuration directly.

What You’ll Build

A row of Freeze up to “Column” buttons — one per column — generated from the column headers array
An Unfreeze all button that resets the freeze boundary to zero
A status indicator showing how many columns are currently frozen
A guard that prevents freezing more columns than are present in the grid

Before you begin

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

The example uses marketing analytics data with eight columns: Campaign, Channel, Impressions, Clicks, Conversions, CPC, Revenue, and ROI. With many columns the grid scrolls horizontally, making frozen columns genuinely useful — the identifier columns stay visible while metric columns scroll.

Step 1 — Set up the grid with fixedColumnsStart and manualColumnMove

1
const hot = new Handsontable(container, {
2
  data,
3
  colHeaders,
4
  columns: [
5
    { data: 'campaign', type: 'text' },
6
    { data: 'channel', type: 'text' },
7
    { data: 'impressions', type: 'numeric', numericFormat: { pattern: '0,0' } },
8
    { data: 'clicks', type: 'numeric', numericFormat: { pattern: '0,0' } },
9
    { data: 'conversions', type: 'numeric', numericFormat: { pattern: '0,0' } },
10
    { data: 'cpc', type: 'numeric', numericFormat: { pattern: '0.00' } },
11
    { data: 'revenue', type: 'numeric', numericFormat: { pattern: '$0,0' } },
12
    { data: 'roi', type: 'numeric', numericFormat: { pattern: '0.00' } },
13
  ],
14
  fixedColumnsStart: 0,
15
  manualColumnMove: true,
16
  rowHeaders: true,
17
  height: 'auto',
18
  width: '100%',
19
  autoWrapRow: true,
20
  licenseKey: 'non-commercial-and-evaluation',
21
});

What’s happening: fixedColumnsStart: 0 is the initial value — no columns are frozen on load. manualColumnMove: true allows users to drag columns into different positions. Both options work together: after the user reorders columns, the freeze boundary still refers to the current visual order (the leftmost n columns in their current positions are frozen).

Why set fixedColumnsStart: 0 explicitly? The default is 0, but declaring it makes the initial state visible in the config and makes the runtime change more explicit to anyone reading the code.

Step 2 — Track state and apply the freeze boundary

1
let frozenCount = 0;
2

3
function freezeUpTo(n) {
4
  const total = hot.countCols();
5

6
  frozenCount = Math.min(n, total);
7
  hot.updateSettings({ fixedColumnsStart: frozenCount });
8
  updateStatus();
9
}

What’s happening: frozenCount is the single piece of mutable state in this recipe. freezeUpTo(n) clamps the requested freeze count to the actual number of columns (hot.countCols()) and then calls hot.updateSettings(). Clamping handles the edge case where a freeze button is clicked after columns have been hidden or removed.

Why use hot.updateSettings() instead of modifying the config object directly? hot.updateSettings() is the documented way to change grid settings at runtime. It triggers a full re-render and keeps Handsontable’s internal state consistent. Modifying a config object directly has no effect on the rendered grid.

Why Math.min(n, total)? If fixedColumnsStart exceeds the number of rendered columns, Handsontable clamps it internally — but being explicit in application code prevents confusion and makes the guard visible.

Step 3 — Generate freeze buttons from the column headers

1
const colHeaders = ['Campaign', 'Channel', 'Impressions', 'Clicks', 'Conversions', 'CPC ($)', 'Revenue ($)', 'ROI'];
2

3
colHeaders.forEach((header, index) => {
4
  const btn = document.createElement('button');
5

6
  btn.type = 'button';
7
  btn.textContent = `Freeze up to "${header}"`;
8
  btn.dataset.colIndex = String(index);
9

10
  btn.addEventListener('click', () => {
11
    freezeUpTo(index + 1);
12
  });
13

14
  controlsContainer.appendChild(btn);
15
});

What’s happening: One button is generated for each column header. Clicking the button for column at index i calls freezeUpTo(i + 1), which freezes columns 0 through i inclusive. Generating buttons from the same colHeaders array ensures the button labels and column positions are always in sync — adding or renaming a column in the config automatically updates the button list.

Why index + 1? fixedColumnsStart is a count, not an index. To freeze the column at visual index i, you set the count to i + 1.

Step 4 — Add the Unfreeze all button

1
document.querySelector('#unfreeze-btn').addEventListener('click', () => {
2
  frozenCount = 0;
3
  hot.updateSettings({ fixedColumnsStart: 0 });
4
  updateStatus();
5
});

What’s happening: Setting fixedColumnsStart: 0 releases all frozen columns. The grid re-renders without any pinned column overlay. The status indicator is updated to “No columns frozen”.

Step 5 — Show a frozen column count indicator

1
function updateStatus() {
2
  statusEl.textContent = frozenCount === 0
3
    ? 'No columns frozen'
4
    : `${frozenCount} column${frozenCount > 1 ? 's' : ''} frozen`;
5
}

What’s happening: updateStatus() is called after every freeze or unfreeze action. It reads frozenCount — not the grid setting — because frozenCount is already clamped and reflects the actual frozen count. The status message uses a simple plural rule to display “1 column frozen” or “3 columns frozen”.

How It Works - Complete Flow

Page load: The grid initializes with fixedColumnsStart: 0. No columns are pinned. The status reads “No columns frozen”. Freeze buttons are generated from colHeaders.
User clicks “Freeze up to ‘Channel’”: freezeUpTo(2) is called. frozenCount becomes 2. hot.updateSettings({ fixedColumnsStart: 2 }) pins the first two columns (Campaign and Channel). The status reads “2 columns frozen”.
User drags a column: Because manualColumnMove: true is set, the user can reorder columns by dragging. After reordering, the frozen count still applies to the current leftmost n columns — whichever columns are now in positions 0 and 1. This is the key caveat: frozen columns are always the leftmost n columns in their current visual order, not a fixed set of named columns.
User clicks “Unfreeze all”: frozenCount resets to 0. hot.updateSettings({ fixedColumnsStart: 0 }) removes all frozen columns. The status reads “No columns frozen”.

What you learned

Set fixedColumnsStart: n in the initial config or via hot.updateSettings() to pin the leftmost n columns.
Call hot.updateSettings({ fixedColumnsStart: 0 }) to unfreeze all columns.
Generate freeze buttons programmatically from the colHeaders array so labels stay in sync with the grid configuration.
fixedColumnsStart is a count from the left edge in current visual order — not a named column reference. After column reordering, the frozen set changes accordingly.
Clamp the freeze count with Math.min(n, hot.countCols()) to handle edge cases where the requested count exceeds the number of visible columns.

Next steps

Combine this pattern with the column visibility toggle recipe to build a full column-management toolbar.
Persist the frozenCount value to localStorage using the afterUpdateSettings hook so the freeze state survives a page refresh.
Replace the individual freeze buttons with a single numeric input (<input type="number">) to let users type a freeze count directly.