Sheets bar

Render a tab bar above or below the grid and let users switch between the sheets of a multi-sheet workbook.

Overview

The SheetsBar plugin renders a tab bar below the grid, or above it with the position option. Each tab represents one sheet, and clicking a tab switches the grid to that sheet’s data. Every sheet owns its own data, its own configuration overrides, and its own runtime view state, such as scroll position and selection.

The plugin is disabled by default. Enable it with the sheetsBar option.

Enable the sheets bar

Set sheetsBar to true to wrap the grid’s existing data into a single sheet named Sheet1, or pass an object with a sheets array to define the workbook up front.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
// Register all Handsontable's modules.
4
registerAllModules();
5
const container = document.querySelector('#example');
6
new Handsontable(container, {
7
    sheetsBar: {
8
        sheets: [
9
            {
10
                name: 'Budget',
11
                data: [
12
                    ['Marketing', 4200, 5100],
13
                    ['Engineering', 18700, 19200],
14
                    ['Operations', 3100, 2900],
15
                ],
16
                settings: {
17
                    colHeaders: ['Category • A', 'Q1 2026 • B', 'Q2 2026 • C'],
18
                },
19
            },
20
            {
21
                name: 'Notes',
22
                data: [
23
                    ['Reviewed by Ana García on 2026-03-14'],
24
                    ['Pending sign-off from Finance'],
25
                ],
26
                settings: {
27
                    colHeaders: ['Note • A'],
28
                },
29
            },
30
        ],
31
        activeSheet: 0,
32
    },
33
    rowHeaders: true,
34
    colHeaders: true,
35
    stretchH: 'all',
36
    height: 240,
37
    licenseKey: 'non-commercial-and-evaluation',
38
});

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

4
// Register all Handsontable's modules.
5
registerAllModules();
6

7
const container = document.querySelector('#example')!;
8

9
new Handsontable(container, {
10
  sheetsBar: {
11
    sheets: [
12
      {
13
        name: 'Budget',
14
        data: [
15
          ['Marketing', 4200, 5100],
16
          ['Engineering', 18700, 19200],
17
          ['Operations', 3100, 2900],
18
        ],
19
        settings: {
20
          colHeaders: ['Category • A', 'Q1 2026 • B', 'Q2 2026 • C'],
21
        },
22
      },
23
      {
24
        name: 'Notes',
25
        data: [
26
          ['Reviewed by Ana García on 2026-03-14'],
27
          ['Pending sign-off from Finance'],
28
        ],
29
        settings: {
30
          colHeaders: ['Note • A'],
31
        },
32
      },
33
    ],
34
    activeSheet: 0,
35
  },
36
  rowHeaders: true,
37
  colHeaders: true,
38
  stretchH: 'all',
39
  height: 240,
40
  licenseKey: 'non-commercial-and-evaluation',
41
});

Click the Budget and Notes tabs to switch between the two sheets. Click the + control to add a new sheet.

Configuration options

You can customize the sheets bar using available settings, such as defining the initial workbook, choosing the sheet that opens first, or showing and hiding the bar’s controls.

Each entry in sheets describes one sheet: its tab label, its source data, and optional grid settings applied while that sheet is active. Settings a sheet does not declare keep their grid-level values.

You can configure the following options:

1
const configurationOptions = {
2
  sheetsBar: {
3
    // Define the initial workbook. When omitted, the grid's
4
    // own data becomes a single sheet named `Sheet1`.
5
    sheets: [
6
      {
7
        // Set the sheet's tab label. When omitted, the sheet gets
8
        // the next free `Sheet{n}` name.
9
        name: 'Budget',
10
        // Provide the sheet's source data
11
        data: [['Item', 'Cost'], ['Rent', 1200]],
12
        // Apply grid settings while this sheet is active
13
        // (for example, `columns` or `colWidths`)
14
        settings: { colWidths: 120 },
15
      },
16
      { name: 'Notes', data: [['Draft']] },
17
    ],
18
    // Set the index (within `sheets`) of the sheet to activate
19
    // on initialization. Passed later through `updateSettings()`
20
    // with a changed value, it switches the active sheet without
21
    // rebuilding the workbook
22
    activeSheet: 0,
23
    // Show or hide the add-sheet and all-sheets menu controls
24
    controls: true,
25
    // Show or hide the tab-scrolling arrows that appear when tabs
26
    // overflow the bar's width
27
    paging: true,
28
    // Render the bar above or below the grid
29
    position: 'bottom',
30
    // Custom container where the sheets bar UI will be injected
31
    // (optional). When omitted, the bar renders in the layout slot
32
    // the `position` option names.
33
    uiContainer: null,
34
  }
35
};

Read more about where the bar renders in the layout slots guide.

Managing sheets programmatically

Get the plugin instance with getPlugin() and call its API methods.

1
const sheetsBar = hot.getPlugin('sheetsBar');
2

3
// list every sheet, in tab order
4
sheetsBar.getSheets();
5
// [{ id: 1, name: 'Budget', isActive: true }, { id: 2, name: 'Notes', isActive: false }]
6

7
// switch the active sheet, by id or by name
8
sheetsBar.setActiveSheet('Notes');
9

10
// append a new sheet
11
sheetsBar.addSheet('Q3 Forecast', [['Category', 'Q3 2026']]);
12

13
// rename, copy, or remove a sheet, by id
14
sheetsBar.renameSheet(2, 'Comments');
15
sheetsBar.duplicateSheet(1);
16
sheetsBar.removeSheet(2);

getSheets() returns a SheetDescriptor for each sheet: its id, its name, and whether it is the active sheet. setActiveSheet() and addSheet() return false (or null for addSheet()) when the operation is rejected — for example, when a beforeSheetTabChange listener cancels a switch. moveSheetToIndex(id, index) moves a sheet to a new tab-order index and returns false when the move is rejected. renameSheet(id, name) and removeSheet(id) return false when the rename or removal is rejected, and duplicateSheet(id) returns a SheetDescriptor for the copy, or null when the copy is rejected.

Tab menus

Each tab has a menu with Rename, Duplicate, Delete, Move left, and Move right actions. Open it with the chevron on the active tab, or right-click any tab. On an inactive tab, the chevron first switches to that sheet — click it again to open the menu. Double-click a tab to rename it inline.

The all-sheets menu — opened from the ≡ control next to the add-sheet button — lists every sheet and lets you jump to any of them, including sheets that are scrolled out of view.

You can also reorder sheets by dragging a tab along the bar. Deleting the active sheet activates its nearest remaining neighbor, and the last remaining sheet can’t be deleted.

Overflow paging

When the tabs no longer fit the bar’s width, paging arrows appear at the end of the strip. Click an arrow to scroll the tabs by one page. Set paging: false to hide the arrows and let the tab strip overflow instead.

Right-to-left layout

Under a right-to-left layout, the tab strip mirrors: the first sheet’s tab renders on the right, and the paging arrows swap direction. The tab menu’s Move left and Move right actions keep referring to the visual direction, not the underlying array order.

Use sheets bar hooks

You can run your code before or after different sheet operations, using the following Handsontable hooks. Every before hook can cancel its operation by returning false.

1
const configurationOptions = {
2
  beforeSheetTabChange(oldSheetId, newSheetId) {
3
    // add your code here
4
    return false; // to block the sheet switch
5
  },
6
  afterSheetTabChange(oldSheetId, newSheetId) {
7
    // add your code here
8
  },
9
  beforeSheetTabRemove(sheetId) {
10
    // add your code here
11
    return false; // to block the removal
12
  },
13
  // ...
14
};

Per-sheet view state

Switching sheets captures the outgoing sheet’s scroll position, selection, sort, filters, hidden and trimmed indexes, merged cells, custom borders, manual column widths and row heights, and any cell-meta changes you made while it was active. It restores that state the next time you switch back to it. A sheet you have not visited yet opens with a neutral view state, so it never inherits the previous sheet’s filters or sizes. The afterSheetTabStateCapture and afterSheetTabStateRestore hooks fire after each capture and restore.

Use formulas across sheets

A sheet can enable the Formulas plugin through its own settings, and its formulas recalculate within that sheet.

Formulas can also reference other sheets of the workbook. Share one HyperFormula instance across the sheets, and give each sheet its own sheetName within that instance:

1
const engine = HyperFormula.buildEmpty({
2
  licenseKey: 'internal-use-in-handsontable',
3
});
4

5
const configurationOptions = {
6
  sheetsBar: {
7
    sheets: [
8
      {
9
        name: 'Rates',
10
        data: [[0.23]],
11
        settings: { formulas: { engine, sheetName: 'Rates' } },
12
      },
13
      {
14
        name: 'Budget',
15
        data: [[100, '=A1*Rates!A1']],
16
        settings: { formulas: { engine, sheetName: 'Budget' } },
17
      },
18
    ],
19
  },
20
};

Editing a value on one sheet recalculates the formulas that reference it on the other sheets. In the demo below, switch to the Rates sheet, change the VAT rate, and return to Budget: the VAT and gross amounts recalculate.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { HyperFormula } from 'hyperformula';
4
// Register all Handsontable's modules.
5
registerAllModules();
6
// One engine, shared by every sheet of the workbook.
7
const engine = HyperFormula.buildEmpty({
8
    licenseKey: 'internal-use-in-handsontable',
9
});
10
const ratesData = [
11
    ['VAT rate', 0.23],
12
    ['Service fee', 0.05],
13
];
14
const container = document.querySelector('#example2');
15
new Handsontable(container, {
16
    sheetsBar: {
17
        sheets: [
18
            {
19
                name: 'Budget',
20
                data: [
21
                    ['Laptops', 4200, '=B1*Rates!B1', '=B1*Rates!B2', '=B1+C1+D1'],
22
                    ['Desks', 1200, '=B2*Rates!B1', '=B2*Rates!B2', '=B2+C2+D2'],
23
                    ['Monitors', 2600, '=B3*Rates!B1', '=B3*Rates!B2', '=B3+C3+D3'],
24
                    ['Chairs', 950, '=B4*Rates!B1', '=B4*Rates!B2', '=B4+C4+D4'],
25
                    ['Docking stations', 780, '=B5*Rates!B1', '=B5*Rates!B2', '=B5+C5+D5'],
26
                    ['Total', '=SUM(B1:B5)', '=SUM(C1:C5)', '=SUM(D1:D5)', '=SUM(E1:E5)'],
27
                ],
28
                settings: {
29
                    colHeaders: ['Item • A', 'Net • B', 'VAT • C', 'Fee • D', 'Gross • E'],
30
                    formulas: { engine, sheetName: 'Budget' },
31
                },
32
            },
33
            {
34
                name: 'Rates',
35
                data: ratesData,
36
                settings: {
37
                    colHeaders: ['Rate • A', 'Value • B'],
38
                    formulas: { engine, sheetName: 'Rates' },
39
                },
40
            },
41
        ],
42
        activeSheet: 0,
43
    },
44
    rowHeaders: true,
45
    colHeaders: true,
46
    stretchH: 'all',
47
    height: 240,
48
    licenseKey: 'non-commercial-and-evaluation',
49
});

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

5
// Register all Handsontable's modules.
6
registerAllModules();
7

8
// One engine, shared by every sheet of the workbook.
9
const engine = HyperFormula.buildEmpty({
10
  licenseKey: 'internal-use-in-handsontable',
11
});
12

13
const ratesData = [
14
  ['VAT rate', 0.23],
15
  ['Service fee', 0.05],
16
];
17

18
const container = document.querySelector('#example2')!;
19

20
new Handsontable(container, {
21
  sheetsBar: {
22
    sheets: [
23
      {
24
        name: 'Budget',
25
        data: [
26
          ['Laptops', 4200, '=B1*Rates!B1', '=B1*Rates!B2', '=B1+C1+D1'],
27
          ['Desks', 1200, '=B2*Rates!B1', '=B2*Rates!B2', '=B2+C2+D2'],
28
          ['Monitors', 2600, '=B3*Rates!B1', '=B3*Rates!B2', '=B3+C3+D3'],
29
          ['Chairs', 950, '=B4*Rates!B1', '=B4*Rates!B2', '=B4+C4+D4'],
30
          ['Docking stations', 780, '=B5*Rates!B1', '=B5*Rates!B2', '=B5+C5+D5'],
31
          ['Total', '=SUM(B1:B5)', '=SUM(C1:C5)', '=SUM(D1:D5)', '=SUM(E1:E5)'],
32
        ],
33
        settings: {
34
          colHeaders: ['Item • A', 'Net • B', 'VAT • C', 'Fee • D', 'Gross • E'],
35
          formulas: { engine, sheetName: 'Budget' },
36
        },
37
      },
38
      {
39
        name: 'Rates',
40
        data: ratesData,
41
        settings: {
42
          colHeaders: ['Rate • A', 'Value • B'],
43
          formulas: { engine, sheetName: 'Rates' },
44
        },
45
      },
46
    ],
47
    activeSheet: 0,
48
  },
49
  rowHeaders: true,
50
  colHeaders: true,
51
  stretchH: 'all',
52
  height: 240,
53
  licenseKey: 'non-commercial-and-evaluation',
54
});

One thing to keep in mind: pass a built engine instance (HyperFormula.buildEmpty()), not the HyperFormula class. The class builds a separate engine for each sheet, and separate engines can’t see each other’s data. The plugin warns in the console when a sheetName rides on the class.

A sheet added at runtime — through the bar’s add button, or through addSheet() without a settings argument — joins the workbook’s shared engine under its own name, so formulas work on it and cross-sheet references can reach it right away. Pass a settings argument to addSheet() to configure the new sheet yourself.

Known limitations

Only one sheet’s data and settings are loaded into the grid at a time.
Passing a changed sheets value through updateSettings() rebuilds the whole workbook, discarding any sheets you added at runtime with addSheet(). A re-passed value counts as unchanged when each sheet’s settings are structurally equal and each sheet’s data is the same array reference. A framework wrapper that re-emits a fresh settings literal on every render therefore keeps the workbook, as long as the data arrays are stable references - inline data literals recreated on each render reset it. A rebuild keeps the active sheet selected by name when the new workbook still contains it and the activeSheet option did not change. Changing only the bar’s UI options (controls, paging, position) never rebuilds the workbook.
Switching sheets calls loadData() internally, which clears the UndoRedo plugin’s undo and redo stacks.
Cell meta set with setCellMeta() survives a switch round trip, except the valid flag - validation results are recomputed by the next validation rather than restored.
The bar shares its container with the grid. When the window scrolls the grid (no height option and no scrollable ancestor), the bar follows the last row, so on a long sheet you scroll past the data to reach it. To keep the bar in view, give the grid an explicit height, or put it in a container with a fixed height and overflow: auto. The Pagination bar behaves the same way.

Each tab is a single stop in the tab order.

Windows	macOS	Action
`Enter` / `Space`	`Enter` / `Space`	Switch to the focused tab’s sheet. On the active tab, open the tab’s menu
Arrow keys	Arrow keys	Move the focus along the tab strip
`Home` / `End`	`Home` / `End`	Move the focus to the first or last tab
`Escape`	`Escape`	Close the open menu, cancel an inline rename, or cancel a drag in progress