SheetsBar

Options

sheetsBar

Can be set at: grid

Ask AI

Source code

sheetsBar.sheetsBar : boolean | object

The sheetsBar option configures the SheetsBar plugin, which renders a tab bar below the grid — or above it, with the position option — and lets the user switch between the sheets of a multi-sheet workbook.

You can set the sheetsBar option to one of the following:

Setting	Description
undefined (default)	Disable the SheetsBar plugin
false	Disable the SheetsBar plugin
true	Enable the SheetsBar plugin

sheetsBar: Additional options

If you set the sheetsBar option to an object, you can set the following SheetsBar plugin options:

Option	Possible settings	Description
sheets	An array of { name, data, settings } objects, or null	Defines the initial workbook. When omitted, the grid’s own data becomes a single Sheet1
activeSheet	A number (default: 0)	The index (within sheets) of the sheet to activate on initialization. Passed later through updateSettings() with a changed value, it switches the active sheet without rebuilding the workbook; a re-passed identical value is ignored
controls	Boolean (default: true)	Controls visibility of the add-sheet and sheet-menu controls
paging	Boolean (default: true)	Controls visibility of the tab-scrolling controls, shown when tabs overflow the bar’s width
position	'top' | 'bottom' (default: 'bottom')	The edge of the grid the bar renders on
uiContainer	An HTML element (default: null)	The container element where the sheets bar UI will be installed. If not provided, the bar is injected below the root table element

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 19.0.0
Example

// enable the `SheetsBar` plugin
sheetsBar: true,

// or, with a predefined workbook
sheetsBar: {
  sheets: [
    { name: 'Budget', data: [['Item', 'Cost'], ['Rent', 1200]] },
    { name: 'Notes', data: [['Draft']] },
  ],
  activeSheet: 0,
},

Members

DEFAULT_SETTINGS

Ask AI

Source code

SheetsBar.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

PLUGIN_KEY

Ask AI

Source code

SheetsBar.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Ask AI

Source code

SheetsBar.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTINGS_VALIDATORS

Ask AI

Source code

SheetsBar.SETTINGS_VALIDATORS

Returns an object of validator functions used to type-check each settings property at runtime.

Methods

addSheet

Ask AI

Source code

sheetsBar.addSheet([name], [data], [settings], [source]) ⇒ object | null

Appends a sheet and returns its descriptor, or null when a beforeSheetTabAdd listener canceled the operation.

When no settings are given and the workbook’s sheets share a formula engine, the new sheet joins it under its own name — the way a spreadsheet’s new sheet does — so formulas work on it and cross-sheet references can reach it right away.

Param	Type	Default	Description
[name]	string		optional The sheet’s name. Omitted, the next free Sheet{n} is used.
[data]	Array<Array>		optional The sheet’s data. Omitted, the sheet starts blank.
[settings]	object		optional The sheet’s settings. Omitted, the sheet inherits the workbook’s shared formula engine when one is configured.
[source]	string	”SheetsBar.api”	optional Operation source tag, passed on to the hooks.

Returns: object | null - A descriptor for the new sheet, or null.

destroy

Ask AI

Source code

sheetsBar.destroy()

Destroys the plugin instance.

disablePlugin

Ask AI

Source code

sheetsBar.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

duplicateSheet

Ask AI

Source code

sheetsBar.duplicateSheet(id, [source]) ⇒ object | null

Duplicates a sheet, placing the copy directly after the original.

The copy carries a deep clone of the sheet’s data and settings, and a name derived from the original. Rejected — and reported as null — when the id is unknown or a beforeSheetTabAdd listener cancels it.

Param	Type	Default	Description
id	number		The sheet to copy.
[source]	string	”SheetsBar.api”	optional Operation source tag, passed on to the hooks.

Returns: object | null - A descriptor for the copy, or null.

enablePlugin

Ask AI

Source code

sheetsBar.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

getSheets

Ask AI

Source code

sheetsBar.getSheets() ⇒ Array<object>

Returns descriptors of all sheets in tab order.

Returns: Array<object> - One { id, name, isActive } descriptor per sheet.

isEnabled

Ask AI

Source code

sheetsBar.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings.

moveSheetToIndex

Ask AI

Source code

sheetsBar.moveSheetToIndex(id, to, [source]) ⇒ boolean

Moves a sheet to an absolute tab index.

The index is a model index, not a visual one — a caller reading positions off the DOM under RTL has already accounted for the mirroring, so nothing is mirrored here.

Param	Type	Default	Description
id	number		The sheet id.
to	number		The target index.
[source]	string	”SheetsBar.api”	optional The operation source reported to the hooks.

Returns: boolean - true when the sheet moved.

removeSheet

Ask AI

Source code

sheetsBar.removeSheet(id, [source]) ⇒ boolean

Removes a sheet.

Removing the active sheet activates its nearest remaining neighbor first, so the grid runs its normal view-state switch. The last remaining sheet cannot be removed. Rejected — and reported as false — when the id is unknown, it is the last sheet, or a beforeSheetTabRemove listener cancels it.

Param	Type	Default	Description
id	number		The sheet to remove.
[source]	string	”SheetsBar.api”	optional Operation source tag, passed on to the hooks.

Returns: boolean - true when the sheet was removed.

renameSheet

Ask AI

Source code

sheetsBar.renameSheet(id, name, [source]) ⇒ boolean

Renames a sheet.

Rejected — and reported as false — when the name is blank, unchanged, already taken by another sheet, already identifying a different sheet in the sheet’s formula engine, or a beforeSheetTabRename listener cancels it.

Param	Type	Default	Description
id	number		The sheet’s id.
name	string		The new name. Trimmed, and cut to the name length limit.
[source]	string	”SheetsBar.api”	optional Operation source tag, passed on to the hooks.

Returns: boolean - true when the sheet was renamed.

setActiveSheet

Ask AI

Source code

sheetsBar.setActiveSheet(idOrName, [source]) ⇒ boolean

Activates a sheet by id or unique name. Returns false when the sheet does not exist, is already active, or a beforeSheetTabChange listener canceled the switch.

Param	Type	Default	Description
idOrName	number string		The sheet’s id, or its name.
[source]	string	”SheetsBar.api”	optional Operation source tag, passed on to the hooks.

Returns: boolean - true when the sheet was activated.

updatePlugin

Ask AI

Source code

sheetsBar.updatePlugin()

Updates the plugin state. This method is executed when Core#updateSettings is invoked.