SpreadsheetGrid
Displays a worksheet with cell selection, frozen panes, zoom and optional cell editing.
import { SpreadsheetGrid } from '@tumblerjs/svelte';
Example
Loading project-budget.xlsx…
Double-click a Quantity or Unit cost cell and change it; Total recalculates. On a phone, scroll the grid sideways to reach those columns.
<script lang="ts">
import { untrack } from 'svelte';
import { createGridSelection } from '@tumblerjs/core';
import { openSpreadsheetArtifact } from '@tumblerjs/sheets';
import {
SpreadsheetGrid,
type SpreadsheetGridEdit,
} from '@tumblerjs/svelte';
let { bytes }: { bytes: Uint8Array } = $props();
let artifact = $state(
untrack(() => openSpreadsheetArtifact(bytes)),
);
let selection = $state(
createGridSelection({ row: 2, column: 1 }),
);
// Each edit returns a new artifact with recalculated formulas.
function edit({ reference, value }: SpreadsheetGridEdit) {
artifact = artifact.editCell(reference, value);
}
</script>
<div class="sheet">
<SpreadsheetGrid
worksheet={artifact.worksheet}
calculation={artifact.calculation}
{selection}
onselectionchange={(next) => (selection = next)}
onedit={edit}
scale={0.75}
/>
</div>
<style>
.sheet { height: 320px; min-width: 0; }
.sheet :global(.tumbler-grid) { height: 100%; }
</style>
Usage
Call openSpreadsheetArtifact(bytes) and pass the result's worksheet and calculation to the grid. The worksheet holds the cells as saved; calculation holds the current formula results. The grid is view-only until you pass onedit. It tracks the selection itself; if another control, such as a formula bar, needs to know which cells are selected, pass selection to set it and onselectionchange to follow it.
The example takes the file contents as a bytes prop. To run it in your app, save the example source as GridPreview.svelte, put project-budget.xlsx in static/, and load it from +page.svelte:
<script lang="ts">
import { onMount } from 'svelte';
import GridPreview from './GridPreview.svelte';
let bytes = $state<Uint8Array>();
onMount(async () => {
const response = await fetch('/project-budget.xlsx');
bytes = new Uint8Array(await response.arrayBuffer());
});
</script>
{#if bytes}<GridPreview {bytes} />{/if}Props
| Prop | Description |
|---|---|
worksheetrequired SpreadsheetWorksheet | The sheet to display, artifact.worksheet. |
calculation SpreadsheetCalculationSnapshot | Formula results, artifact.calculation. Without it the grid shows the values last saved in the file, so results go stale after an edit. |
selection GridSelection | The selected cell or range. Create one with createGridSelection. Defaults to A1. |
onselectionchange (selection: GridSelection) => void | Called when the user selects a different cell or range. |
onedit (edit: SpreadsheetGridEdit) => void | Called with { reference, value } when the user commits a cell edit. Passing it turns on editing. Apply the edit with artifact.editCell(reference, value) and assign the returned artifact. |
scale number | Bindable zoom factor, where 1 is 100%. Pinch and Ctrl + wheel keep it between 0.25 and 3. |
readonly boolean | Turns off cell editing and moving drawings, even when onedit is set. Selection and scrolling still work. |