SpreadsheetGrid

Displays a worksheet with cell selection, frozen panes, zoom and optional cell editing.

import { SpreadsheetGrid } from '@tumblerjs/svelte';

Example

Preview

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.

GridPreview.svelte
<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:

+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}

Guide: Open a spreadsheet →

Props

PropDescription
worksheetrequired SpreadsheetWorksheetThe sheet to display, artifact.worksheet.
calculation SpreadsheetCalculationSnapshotFormula results, artifact.calculation. Without it the grid shows the values last saved in the file, so results go stale after an edit.
selection GridSelectionThe selected cell or range. Create one with createGridSelection. Defaults to A1.
onselectionchange (selection: GridSelection) => voidCalled when the user selects a different cell or range.
onedit (edit: SpreadsheetGridEdit) => voidCalled 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 numberBindable zoom factor, where 1 is 100%. Pinch and Ctrl + wheel keep it between 0.25 and 3.
readonly booleanTurns off cell editing and moving drawings, even when onedit is set. Selection and scrolling still work.