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, such as decimal separator and currency symbol. 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. |
readonly | boolean | Enable read-only mode. Users can navigate, select, copy and search the cells, and edits are refused. See JS API: readonly. |
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. |
selection | boolean | Turn the selection of cells on and off. Default: true. With false, the spreadsheet has no active cell, and the cells can't be selected or edited from the UI. See JS API: selection. |
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. |
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} />
Toolbar customization
<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/next/worker.js"
exportModulePath="../libs/json2excel/next/worker.js"
/>
To use a specific version, replace next with the version number (check the Excel2Json and Json2Excel GitHub repositories).
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
In read-only mode, users can navigate the cells with the keyboard, select them with the mouse, copy and search them. Edits are refused and announced to screen readers. Since readonly is an init-only prop, changing it recreates the widget. The data is kept, while the undo/redo history and the UI state (selection, scroll position) are reset.
<ReactSpreadsheet sheets={sheets} readOnly={true} />
To turn off the keyboard navigation and the selection as well, add selection={false}. The selection prop is applied at runtime, so it can be switched without recreating the widget:
<ReactSpreadsheet sheets={sheets} readOnly={true} selection={false} />
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} />