# Spreadsheet: getting started The one component a spreadsheet needs, how it takes data, how a formula reaches another sheet, and the document underneath that a save and a reload go through. The other spreadsheet tutorials assume this one, and [The spreadsheet shell](https://svgrid.com/docs/help/cells/spreadsheet-shell/) is the reference behind all of them: every prop, every dialog, the file formats, the limits. `SvSheet` is a spreadsheet, not a mode of the grid: it owns a workbook of formulas, address-keyed formats, comments and rules, and draws it with `` underneath. It ships in `@svgrid/enterprise` on top of `@svgrid/grid`; `jszip` is a peer you add only when a file is saved or opened as `.xlsx` or `.ods`. ```bash npm install @svgrid/grid @svgrid/enterprise ``` > Video: Install the SvGrid spreadsheet The examples on this page share one setup: a small budget as raw text, and the lookup that formats a rectangle of cells by row and column index. ```svelte ``` ## The minimum No props at all is a working spreadsheet: fifty rows, twelve columns, the ribbon, the formula bar, the sheet tabs and the status bar. Click a cell and type a number, or `=SUM(A1:A5)`, and the Excel keyboard is already live: `Ctrl+Arrow` to the edge of a block, `Ctrl+D` and `Ctrl+R` to fill down and right, `Ctrl+;` for today, `Alt+=` for AutoSum, `Ctrl+Z` for a whole action rather than one cell. ```svelte ``` > Live demo: Blank sheet - just type - https://svgrid.com/demos/207-blank-sheet/ ## Seed it with data `data` takes the sheets to start with, each a name and its cells as raw text, row by row. A ragged row is fine; a missing cell reads as empty. Numbers are digits, dates are `yyyy-mm-dd`, and a formula is the text that starts with `=`, exactly as the user would have typed it - the sheet works the values out. ```svelte ``` Change any month and the row's Q1 and the Total row recompute. What the sheet keeps is the text, so `getState()` (below) hands back `=SUM(B2:D2)`, not `7200`. ## A formula that reads another sheet A workbook with more than one sheet is `createWorkbook`, which takes the same list `data` does and gives you the object the formulas run through. A reference qualifies the sheet the way Excel writes it: `Prices!B2`, or `'Price list'!B2` when the name has a space. `$` pins a row or a column when the formula is filled down. ```svelte ``` Switch to the Prices tab, change a price, and switch back: the amounts followed. `Ctrl+PageUp` and `Ctrl+PageDown` move between sheets from the keyboard, and `Shift+F11` adds one. [Workbooks](https://svgrid.com/docs/help/cells/workbooks/) is the page on sheets that read each other; [Formulas](https://svgrid.com/docs/help/sheet/formulas/) is the page on what a formula can say. ## A look it opens with A sheet a person types into can be formatted by hand from the ribbon. A sheet you ship should open formatted, or it is a grid of raw numbers until someone tidies it. `formats` takes cell formats keyed by address (`'Orders!F2'` reaches another sheet), and `columnWidths` widths keyed by letter: ```svelte ``` One entry per address gets long by row six, which is what the document below is for. [Formatting](https://svgrid.com/docs/help/sheet/formatting/) covers number formats, borders, merged headers and the rules that colour a cell by its value. ## The document Everything the shell shows beyond the cells lives in a sheet document: per sheet its formats, column widths and row heights, hidden lines, frozen panes, comments, protection, page setup, charts, validation and conditional formatting rules. `createSheetDocument` builds one around a workbook, `doc.get(name)` is a sheet's part of it, and the `document` prop hands the whole thing to the component. `formats.set` formats a rectangle at a time, which is how a header row or a money column is one line: ```svelte ``` The header stays put when the sheet scrolls, because `freeze` is part of the document too. So is what the user does next: a format from the ribbon, a widened column, a new comment all land in `doc`, and `doc.getState()` is the whole thing as plain JSON. `onChange` fires once per tick with the reasons since the last call, so an autosave is one handler: ```svelte save(doc.getState())} /> ``` [Files](https://svgrid.com/docs/help/sheet/files/) takes it from there: what the state holds, restoring it, `.xlsx` in and out, and the three things a network makes you think about. ## Rows into a sheet A grid's rows, or an API's, become a sheet with `sheetCellsFromRows`: a header row of labels, a row per record with each value as the text the engine reads, and with `totals` a `=SUM` under every column that held a number. It is how a dataset turns into something the user can add a formula to. ```svelte ``` A boolean lands as `TRUE` or `FALSE`, a `Date` as `yyyy-mm-dd`, a null as nothing. ## The ribbon is Excel's File, Home, Insert, Page Layout, Formulas, Data, Review and View, with Excel's buttons under them and Excel's shortcuts beside them: `Ctrl+B` and the Bold button call the same function, and the button lights up because the cell is bold, not because it was clicked. Every action reaches an `onAction` handler first, so an app can take one over (its own file picker on Open, its own dialog on Goal Seek) by returning `true`. > Live demo: Spreadsheet + Ribbon bar - https://svgrid.com/demos/27-spreadsheet-ribbon/ In a narrow frame, this page's examples included, a ribbon group that does not fit folds into one button named for the group, so Home > Cells > Format is a click deeper than on a full-width sheet. The `look` prop paints the shell with the app's `--sg-*` tokens (`'theme'`, the default) or pins Excel's own palette and geometry (`'excel'`). `showRibbon`, `showFormulaBar`, `showTabs` and `showStatusBar` hide any part of the chrome, and `height="100%"` fills a flex parent. ## See also - [The spreadsheet shell](https://svgrid.com/docs/help/cells/spreadsheet-shell/) - every prop, every dialog, the file formats and the limits, on one page. - [Formulas](https://svgrid.com/docs/help/sheet/formulas/) - references, names, LET and LAMBDA, your own functions, auditing. - [Formatting](https://svgrid.com/docs/help/sheet/formatting/) - number formats, borders, merged headers, conditional formatting. - [Files](https://svgrid.com/docs/help/sheet/files/) - save, restore, autosave, `.xlsx`, `.ods`, `.xls` and `.csv`. - [Excel keyboard shortcuts](https://svgrid.com/docs/help/cells/keyboard-shortcuts/) - the full list, and how to turn them on for a plain grid. - [``](https://svgrid.com/docs/help/web-components/sv-sheet/) - the same component as a custom element for React, Vue, Angular or plain HTML. --- SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/sheet/start/ . All docs: https://svgrid.com/llms.txt