Props reference

All props are optional. The component renders an empty spreadsheet with default settings when no props are provided.

Init-only props

Changing any of these props causes the widget to be destroyed and recreated. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset.

Prop	Type	Description
`menu`	`boolean`	Show the context menu. See JS API: `menu`.
`editLine`	`boolean`	Show the formula/edit line above the grid. See JS API: `editLine`.
`toolbarBlocks`	`ToolbarBlocks[]`	Toolbar blocks to display. See JS API: `toolbarBlocks`.
`multiSheets`	`boolean`	Enable multiple sheet tabs. See JS API: `multisheets`.
`formats`	`IFormats[]`	Custom number format definitions. See JS API: `formats`.
`localization`	`ISpreadsheetConfig["localization"]`	Number/date formatting locale (decimal separator, currency symbol, etc.). Separate from `spreadsheetLocale`. See JS API: `localization`.
`importModulePath`	`string`	Path to the XLSX import module. See JS API: `importModulePath`.
`exportModulePath`	`string`	Path to the XLSX export module. See JS API: `exportModulePath`.
`spreadsheetLocale`	`SpreadsheetLocale`	UI translations and localized formula names. Separate from `localization`.

warning

Changing any init-only prop triggers a full destroy/recreate cycle. Undo/redo history, selection, and scroll position will be reset.

Runtime props

These props are applied immediately without destroying the widget. No data loss or UI state reset.

Prop	Type	Description
`rowsCount`	`number`	Number of rows in the grid. See JS API: `rowsCount`.
`colsCount`	`number`	Number of columns in the grid. See JS API: `colsCount`.
`readonly`	`boolean`	Enable read-only mode. See JS API: `readonly`.

Data props

The sheets prop is the single source of truth for all spreadsheet content. Changes are applied incrementally: only modified cells, ranges, or settings are updated in the widget.

Prop	Type	Description
`sheets`	`SheetData[]`	The single source of truth for all spreadsheet data. Each entry represents a sheet with its cells, structure, and metadata. Changes are applied incrementally.
`styles`	`Record<string, Record<string, string>>`	Shared CSS style definitions referenced by `CellData.css`. Keys are class names, values are CSS property maps. See Styles example.
`activeSheet`	`Id`	Id of the active (visible) sheet. Changing this switches the displayed sheet tab.

warning

Changing styles triggers a full data reload. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset.

Search props

Controls the search bar state from outside the component. Use it together with onSearchResults to build a custom search UI.

Prop	Type	Description
`search`	`SearchConfig`	Controlled search state. Pass a `SearchConfig` object to trigger/update search. Pass `undefined` to dismiss the search bar.

Data loading props

Load spreadsheet data from a remote URL instead of supplying it through the sheets prop.

Prop	Type	Description
`loadUrl`	`string`	URL to load spreadsheet data from. If both `loadUrl` and `sheets` are provided, `sheets` takes precedence.
`loadFormat`	`FileFormat`	File format hint for `loadUrl`. Default: `"json"`.

Theme prop

Controls the visual theme applied to the spreadsheet. Since theme is a runtime prop, the widget updates immediately when the value changes.

Prop	Type	Description
`theme`	`SpreadsheetTheme`	Color theme. Built-in values: `"light"`, `"dark"`, `"contrast-light"`, `"contrast-dark"`. Also accepts custom theme name strings. See Themes.

Container props

Standard React DOM props applied to the wrapper <div> that contains the spreadsheet. Use them to control sizing and layout.

Prop	Type	Description
`className`	`string`	CSS class name appended to the wrapper `<div>`.
`style`	`React.CSSProperties`	Inline styles applied to the wrapper `<div>`.

Examples

Sheets with cell data

A full SheetData example with cells, row and column sizing, merged ranges, and a frozen header row.

const [sheets, setSheets] = useState<SheetData[]>([
    {
        id: "sheet1",
        name: "Budget",
        cells: {
            A1: { value: "Item", css: "header" },
            B1: { value: "Amount", css: "header", format: "currency" },
            A2: { value: "Rent" },
            B2: { value: 2000, format: "currency" },
            A3: { value: "=SUM(B2:B3)" },
        },
        rows: { 0: { height: 40 } },
        cols: { 0: { width: 150 }, 1: { width: 120 } },
        merged: [{
            from: { row: 0, column: 0 },
            to: { row: 0, column: 1 }
        }],
        freeze: { row: 1 },
    },
]);

<ReactSpreadsheet sheets={sheets} activeSheet="sheet1" />

Styles example

Define named styles as CSS property maps in the styles prop, then reference them by name via CellData.css.

const styles = {
    header: {
        "font-weight": "bold",
        "background": "#e3f2fd",
        "color": "#1565c0",
    },
    highlight: {
        "background": "#ffeb3b",
        "color": "#333",
    },
};

<ReactSpreadsheet sheets={sheets} styles={styles} />

<ReactSpreadsheet
    sheets={sheets}
    toolbarBlocks={["undo", "colors", "decoration", "align", "format"]}
/>

Multi-sheet mode

Enable sheet tabs with multiSheets={true}. Pass false to hide the tab bar entirely.

<ReactSpreadsheet sheets={sheets} multiSheets={true} />

<ReactSpreadsheet sheets={sheets} multiSheets={false} />

Excel import/export

<ReactSpreadsheet
    sheets={sheets}
    importModulePath="../libs/excel2json/1.0/worker.js"
    exportModulePath="../libs/json2excel/1.0/worker.js"
/>

European number formatting

<ReactSpreadsheet
    sheets={sheets}
    localization={{
        decimal: ",",
        thousands: ".",
        currency: "€",
    }}
/>

Controlled search

Pass a SearchConfig object to open the search bar programmatically. Use onSearchResults to receive the matching cell references.

const [search, setSearch] = useState<SearchConfig | undefined>();
const [results, setResults] = useState<string[]>([]);

<input onChange={(e) =/> setSearch({ query: e.target.value, open: true })} />
<button onClick={() => setSearch(undefined)}>Close Search</button>
<p>Found in: {results.join(", ")}</p>

<ReactSpreadsheet
    sheets={sheets}
    search={search}
    onSearchResults={setResults}
/>

Theme switching

const [theme, setTheme] = useState<SpreadsheetTheme>("light");

<select onChange={(e) => setTheme(e.target.value as SpreadsheetTheme)}>
    <option value="light">Light</option>
    <option value="dark">Dark</option>
    <option value="contrast-light">Contrast Light</option>
    <option value="contrast-dark">Contrast Dark</option>
</select>

<ReactSpreadsheet sheets={sheets} theme={theme} />

Read-only mode

<ReactSpreadsheet sheets={sheets} readOnly={true} />

Loading data from URL

<ReactSpreadsheet loadUrl="/api/spreadsheet-data" loadFormat="json" />

Locked cells

Mark individual cells as non-editable with locked: true. Unlike readonly, this protects specific cells while leaving the rest of the sheet editable.

const sheets: SheetData[] = [
    {
        id: "sheet1",
        name: "Protected",
        cells: {
            A1: { value: "Header", locked: true },
            A2: { value: "Editable" },
        },
    },
];

<ReactSpreadsheet sheets={sheets} />

Cell validation

Pass an array of strings to CellData.validation to restrict the cell to a dropdown of allowed values.

const sheets: SheetData[] = [
    {
        id: "sheet1",
        name: "Form",
        cells: {
            A1: { value: "Status" },
            B1: { validation: ["Active", "Inactive", "Pending"] },
        },
    },
];

<ReactSpreadsheet sheets={sheets} />

Init-only props​

Runtime props​

Data props​

Search props​

Data loading props​

Theme prop​

Container props​

Examples​

Sheets with cell data​

Styles example​

Toolbar customization​

Multi-sheet mode​

Excel import/export​

European number formatting​

Controlled search​

Theme switching​

Read-only mode​

Loading data from URL​

Locked cells​

Cell validation​