Toolbar and ribbon

Set config to show the built-in toolbar, or config: { ribbon: true } to show an Excel-style ribbon instead.

const grid = createGrid(host, { workbook, config: { ribbon: true } });
console.log(grid.getCommandState("undo").disabled); // true: no history yet

The ribbon appears above the grid with the Home, Insert, Data and View tabs.

Try it live → Spreadsheet showcase

import { createGrid, initSheetwrite, type Workbook } from "@sheetwrite/core";
import "@sheetwrite/core/styles.css";

const host = document.querySelector<HTMLElement>("#grid");
if (host === null) throw new Error("Missing #grid host");
host.style.height = "480px";

const workbook: Workbook = {
  activeSheet: "budget",
  sheets: [
    {
      id: "budget",
      name: "Budget",
      rowCount: 100,
      columns: [
        { key: "item", header: "Item", width: 200, type: "text" },
        { key: "cost", header: "Cost", width: 120, type: "number" },
      ],
    },
  ],
};

await initSheetwrite();
const grid = createGrid(host, { workbook, config: { ribbon: true } });
console.log(grid.getCommandState("undo").disabled); // true: no history yet

Ribbon

The ribbon has four tabs with Excel's group names, labels and order:

Every control reads the same getCommandState contract as host chrome. It disables while the grid is read-only.

Narrow widths

As the grid narrows, the ribbon shrinks the way Excel does:

1. Large buttons become small ones.
2. Labels go.
3. Whole groups fold into one dropdown button that opens the group in a popup.

Groups fold in Excel order. On Home, Editing folds first, then Cells, Number, Alignment, Clipboard, Font and Undo.

Double-click a tab, or use the arrow at the right, to hide the panel and keep only the tab row. The grid takes the space back.

Keyboard

Loading

The ribbon loads with import() as its own chunk, only when a grid asks for it. A grid without the ribbon does not download it; that is about 25 KB less minified JavaScript.

• The grid reserves the ribbon's height while the chunk loads, so nothing moves when it arrives.
• A chunk that arrives after the chrome was rebuilt, or after the grid was destroyed, is dropped.
• If the chunk fails to load, the grid shows the flat toolbar. The load error is still reported as an unhandled promise rejection; the host cannot catch it.

Ribbon outside the grid

The composable shell mounts the same ribbon. Pass ribbon: true to createSpreadsheetShell, or call createRibbon to place it yourself:

import { createRibbon } from "@sheetwrite/core/shell";

const ribbonHost = document.createElement("div");
host.before(ribbonHost);
const ribbon = createRibbon(ribbonHost, grid, {
  focusGrid: () => host.focus(),
  onHeightChange: (height) => console.log(`ribbon is ${height}px tall`),
});

// During teardown; safe to call twice.
ribbon.destroy();

The ribbon styles itself from the same --sheetwrite-widget-*, --sheetwrite-toolbar-* and --sheetwrite-menu-* properties as the toolbar, so light, dark and host themes apply.

GridConfig (toolbar)

Each flag toggles one control. When config is present, every flag except export and ribbon defaults to true. toolbar: false suppresses the toolbar entirely.

createGrid(host, { workbook, config: {} });                 // toolbar with the default controls
createGrid(host, { workbook, config: { sort: false } });    // toolbar, no sort controls
createGrid(host, { workbook, config: { export: true } });   // toolbar with CSV and XLSX buttons
createGrid(host, { workbook, config: { toolbar: false } }); // no toolbar
createGrid(host, { workbook });                             // no toolbar (config omitted)

¹ "Default true" means: when you supply a config object at all. With no config there is no toolbar.

The underline and strikethrough toggles show when bold or italic is on.

Toolbar actions

Every control acts on the current selection; see Interaction → Selection model. A custom toolbar: ToolbarItem[] list names built-in actions, separators, or onClick(grid) callbacks:

createGrid(host, {
  workbook,
  config: {
    toolbar: [
      { action: "undo" },
      { action: "redo" },
      { action: "separator" },
      { action: "bold" },
      { title: "Clear highlights", icon: "Clear", onClick: (grid) => grid.highlightCells(null) },
    ],
  },
});

Built-in action names: bold, italic, underline, strikethrough, alignLeft, alignCenter, alignRight, alignTop, alignMiddle, alignBottom, wrap, textColor, fillColor, border, clearFormat, merge, unmerge, sortAsc, sortDesc, exportCsv, exportXlsx, undo, redo and separator.

Export buttons

• The export flag always enables CSV. The XLSX button requires an explicit optional installation and import "@sheetwrite/xlsx/register" before use. The framework packages do not install an XLSX backend.
• Direct grid.exportXlsx(...) calls reject on failure.
• Built-in toolbar and context-menu actions show an alert and emit one export-error event for CSV or XLSX failures.
• grid.actions.exportXlsx() returns a promise that does not reject.
• Built-in buttons show a busy state and ignore repeated starts while their command is pending.

Host-owned command state

Host chrome can use grid.actions without duplicating selection or history logic. Query one command with grid.getCommandState(name), or subscribe to the complete snapshot through command-state-change (onCommandStateChange in React and Svelte, @command-state-change in Vue):

const update = (bold: GridCommandState, undo: GridCommandState) => {
  undoButton.disabled = undo.disabled;
  boldButton.disabled = bold.disabled;
  boldButton.setAttribute(
    "aria-pressed",
    bold.activity === "mixed" ? "mixed" : String(bold.activity === "active"),
  );
};

update(grid.getCommandState("bold"), grid.getCommandState("undo"));
const stop = grid.on("command-state-change", ({ states }) => {
  update(states.bold, states.undo);
});

boldButton.addEventListener("click", () => grid.actions.toggleBold());
undoButton.addEventListener("click", () => grid.actions.undo());

// Run during host teardown.
stop();

The built-in toolbar uses the same contract, including native disabled and aria-pressed="mixed".

Feature flags

These GridConfig fields enable behavior outside the toolbar row:

Undo, redo and find are keyboard-driven and work without the toolbar: Ctrl+Z undoes the last edit, Ctrl+Shift+Z redoes it, and Ctrl+F opens the find widget (unless find: false).

Edge cases and limits

• The per-control flags apply to the flat toolbar only, not to the ribbon.
• A custom toolbar: [...] item list still renders the flat toolbar, even with ribbon: true.
• toolbar: false removes both the toolbar and the ribbon.
• Command-state aggregation is bounded. Very large selections conservatively report mixed instead of forcing an unbounded cell walk.
• grid.setConfig(config) reconfigures the built-in chrome without replacing the grid or clearing selection and history.

See also

• Context menu
• Search
• Grid methods
• Styling → Widget and context-menu styling
• Generated GridConfig, GridActions, GridCommandState and createRibbon contracts