@8sheets/react
v1.6.0
Published
React component for 8sheets, the Excel-compatible spreadsheet: <Sheet> with typed props, events and ref.
Maintainers
Readme
8sheets for React
<Sheet> puts an 8sheets workbook, an Excel-compatible spreadsheet, in a React app. It works with React 18 and 19, StrictMode included, and with server rendering. Props, events and the ref are typed.
Install
npm i @8sheets/react @8sheets/coreUse
import { useRef } from 'react';
import { Sheet } from '@8sheets/react';
export function Budget() {
const sheet = useRef(null);
return (
<div style={{ height: 480 }}>
<Sheet
ref={sheet}
options={{ chrome: 'light', parts: { titleBar: false } }}
onReady={(wb) => { wb.activeSheet.range('A1').values = [['Item', 'Cost']]; }}
onCellsChanged={(e) => console.log(e.count, 'cells changed')}
onBeforeSheetRemove={(e) => e.cancel()}
/>
</div>
);
}The component renders one <div> that fills its container, so the container needs a height.
optionsgoes tomountWorkbook:parts,chrome,theme,fileName,language,data,sheetsand every option in the API reference. After mount it is compared by value, and only the changed keys go towb.setOptions, with no remount.dataandsheetsact only at mount.- Events are props:
onplus the event name in camel case (onCellsChanged,onSelectionChanged,onBeforeSheetRemove). Calle.cancel()in abefore…handler to stop the action. Only the events you pass a handler for are subscribed. onReady(wb)gives the workbook once it is mounted;onError(err)reports a failed mount or an optionsetOptionsrefused.- The ref (
SheetRef) hasworkbook,openFile(file)andsaveXlsx(sink). - On unmount the workbook is destroyed, with its listeners and Worker.
Next.js
sheet.js is marked 'use client' and mounts in an effect, so a server component can render <Sheet> and the server sends an empty <div>. Handler props are functions, so pass them from a client component. To keep 8sheets out of the server bundle entirely, load it with dynamic(() => import('@8sheets/react').then((m) => m.Sheet), { ssr: false }) in a client component; dynamic() doesn't forward refs, so use onReady there. Both Turbopack and webpack build it with no configuration.
Vite
// vite.config.js
export default defineConfig({
worker: { format: 'es' },
optimizeDeps: { exclude: ['@8sheets/core', '@8sheets/react'] },
});The Workers are ES modules. optimizeDeps.exclude is needed only before Vite 8: the older dependency pre-bundling moves the 8sheets modules away from their Workers, so files can't be opened or saved in vite dev. On Vite 8 you can leave it out.
Documentation
React, Vue and Angular, For developers and the API reference for everything on the workbook.
Licence
8sheets is commercial software, not open source. You may install it and try it for free, to evaluate it. Using it in a product, or deploying it for your users or your own staff, needs a licence from 8sheets.com/pricing: Internal 999 USD or SaaS / OEM 2,999 USD, each paid once per company and covering every developer and every deployment, or Enterprise, quoted. There is no licence key and nothing in the package checks for one. The terms are in LICENSE.md and, once you hold a licence, the 8sheets Source Licence.
