@worksheet-js/vue

Industrial-grade spreadsheet UI engine for Vue 3.

@worksheet-js/vue brings the power of the Worksheet.js canvas rendering engine to the Vue 3 ecosystem. It provides a native Vue 3 component with Composition API support and a useWorksheet composable for full imperative access to the core instance.

Table of Contents

• Installation
• License Initialization
• Quick Start
• Advanced Usage
  • Using useWorksheet
  • Loading XLSX Files
  • Listening to Events
  • Performance Monitoring
• Component API
• Options Reference
• TypeScript
• Nuxt / SSR
• License

Installation

npm install @worksheet-js/core @worksheet-js/vue chart.js
# or
pnpm add @worksheet-js/core @worksheet-js/vue chart.js
# or
yarn add @worksheet-js/core @worksheet-js/vue chart.js

Peer dependencies:

| Package | Required Version | | :--------- | :--------------- | | vue | ^3.0.0 | | chart.js | >= 4.0.0 |

License Initialization

@worksheet-js/core is proprietary software. Call initializeLicense() once at application startup, before any spreadsheet is rendered — typically in main.ts.

// main.ts
import { createApp } from 'vue';
import { initializeLicense } from '@worksheet-js/core';
import App from './App.vue';

initializeLicense('YOUR-LICENSE-KEY');

createApp(App).mount('#app');

To obtain a license key, contact [email protected].

Quick Start

<template>
  <div style="width: 100vw; height: 100vh;">
    <Worksheet :options="options" />
  </div>
</template>

<script setup lang="ts">
import { Worksheet } from '@worksheet-js/vue';
// initializeLicense() called in main.ts

const options = {
  worksheets: [{ worksheetName: 'Sheet1' }],
  toolbar: true,
  formulaBar: true,
};
</script>

Advanced Usage

Using useWorksheet

useWorksheet() returns a ShallowRef whose .value.instance exposes the full @worksheet-js/core API.

<template>
  <div style="height: 600px;">
    <Worksheet ref="wsRef" :options="options" />
  </div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue';
import { Worksheet, useWorksheet } from '@worksheet-js/vue';

const wsRef = useWorksheet();
const options = {
  worksheets: [{ worksheetName: 'Dashboard' }],
  toolbar: true,
};

onMounted(() => {
  const ws = wsRef.value?.instance;
  if (!ws) return;

  // Populate headers
  ws.setValue('A1', 'Product');
  ws.setValue('B1', 'Q1');
  ws.setValue('C1', 'Q2');
  ws.setValue('D1', 'Total');

  // Style headers
  ['A1', 'B1', 'C1', 'D1'].forEach((addr) => {
    ws.setStyle(addr, { bold: true, backgroundColor: '#1a1a2e', color: '#ffffff' });
  });

  // Data with formula
  ws.setValue('A2', 'Widget A');
  ws.setValue('B2', '15000');
  ws.setValue('C2', '18000');
  ws.setValue('D2', '=SUM(B2:C2)');
});
</script>

Loading XLSX Files

<template>
  <div>
    <input type="file" accept=".xlsx,.csv" @change="handleFile" />
    <div style="height: 500px;">
      <Worksheet ref="wsRef" :options="options" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { Worksheet, useWorksheet } from '@worksheet-js/vue';

const wsRef = useWorksheet();
const options = { worksheets: [{ worksheetName: 'Import' }] };

async function handleFile(e: Event) {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file || !wsRef.value?.instance) return;
  await wsRef.value.instance.importFromFile(file);
}
</script>

Listening to Events

<template>
  <div>
    <p>
      Selection: <strong>{{ selection }}</strong>
    </p>
    <div style="height: 400px;">
      <Worksheet ref="wsRef" :options="options" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { Worksheet, useWorksheet } from '@worksheet-js/vue';

const wsRef = useWorksheet();
const options = { worksheets: [{ worksheetName: 'Data' }] };
const selection = ref('—');

onMounted(() => {
  const ws = wsRef.value?.instance;
  if (!ws) return;

  ws.on('onselection', (_sheet, x1, y1, x2, y2) => {
    selection.value = `[${x1},${y1}] → [${x2},${y2}]`;
  });

  ws.on('onchange', (_sheet, _cell, x, y, value) => {
    console.log(`[${x},${y}] → ${value}`);
  });
});

onUnmounted(() => {
  wsRef.value?.instance?.destroy();
});
</script>

Performance Monitoring

<template>
  <div style="height: 500px;">
    <Worksheet ref="wsRef" :options="options" />
  </div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { Worksheet, useWorksheet } from '@worksheet-js/vue';

const wsRef = useWorksheet();
const options = { worksheets: [{ worksheetName: 'Monitor' }] };

let perfInterval: ReturnType<typeof setInterval>;

onMounted(() => {
  const ws = wsRef.value?.instance;
  if (!ws) return;

  perfInterval = setInterval(() => {
    const snap = ws.getPerfSnapshot();
    console.table({
      'Render P95 (ms)': snap.renderMs.p95,
      'Paint P95 (ms)': snap.paintMs.p95,
      'Scroll FPS (mean)': snap.scrollFps.mean,
      'Formula P95 (ms)': snap.formulaMs.p95,
      'Cell Memory (KB)': snap.estimatedCellMemoryKB.mean,
    });
  }, 5000);
});

onUnmounted(() => {
  clearInterval(perfInterval);
  wsRef.value?.instance?.destroy();
});
</script>

Component API

<Worksheet> Props

| Prop | Type | Default | Description | | :---------- | :----------------- | :------ | :--------------------------------------------------------------------------------------------------------------------- | | options | WorksheetOptions | — | Required. Configuration passed to @worksheet-js/core. Do not include container — it is managed internally. | | className | string | '' | CSS class name applied to the wrapper <div>. | | style | Object | {} | Inline styles applied to the wrapper <div>. |

Exposed Instance (via ref)

When using a template ref with useWorksheet(), ref.value exposes:

| Property | Type | Description | | :------------------------- | :------------------------- | :-------------------------------------------- | | instance | Worksheet | The underlying @worksheet-js/core instance. | | worksheet | Worksheet | Alias for instance. | | getValue(address) | (string) => string | Shortcut: read a cell value. | | setValue(address, value) | (string, string) => void | Shortcut: write a cell value. |

All methods available on instance are the full core API:

wsRef.value?.instance.getValue('A1');
wsRef.value?.instance.setValue('B2', '=SUM(A1:A10)');
wsRef.value?.instance.setStyle('A1', { bold: true });
wsRef.value?.instance.importFromFile(file);
wsRef.value?.instance.exportXlsx('report.xlsx');
wsRef.value?.instance.addWorksheet({ worksheetName: 'Sheet2' });
wsRef.value?.instance.setZoom(125);
wsRef.value?.instance.getPerfSnapshot();
wsRef.value?.instance.on('onchange', handler);
wsRef.value?.instance.destroy();

See the @worksheet-js/core documentation for the complete API reference.

Options Reference

Pass all configuration via the :options prop. The container property is managed by the component.

| Option | Type | Default | Description | | :----------------- | :----------------------------- | :-------: | :--------------------------------------------------- | | worksheets | Partial<SheetMeta>[] | [{}] | Initial sheet tabs (name, dimensions, frozen panes). | | toolbar | boolean | true | Show the ribbon toolbar. | | formulaBar | boolean | true | Show the formula input bar. | | theme | 'light' \| 'dark' | 'light' | Color theme. | | defaultColWidth | number | 100 | Default column width in pixels. | | defaultRowHeight | number | 24 | Default row height in pixels. | | frozenRows | number | 0 | Rows frozen at the top. | | frozenCols | number | 0 | Columns frozen at the left. | | licenseKey | string | — | License key (alternative to initializeLicense()). | | onSave | (data: any) => Promise<void> | — | Callback for Ctrl+S / save button. |

TypeScript

All exports are fully typed. Import types from @worksheet-js/core:

import type {
  WorksheetOptions,
  CellStyle,
  SelectionRange,
  SheetMeta,
  CellAddress,
} from '@worksheet-js/core';
import { Worksheet, useWorksheet } from '@worksheet-js/vue';

const options: WorksheetOptions = {
  worksheets: [{ worksheetName: 'Typed Sheet' }],
  toolbar: true,
  theme: 'dark',
};

Nuxt / SSR

Because Worksheet.js uses canvas and Web Workers, it must run in a browser environment. In Nuxt, wrap the component with <ClientOnly> and call initializeLicense() in a plugin:

// plugins/worksheet.client.ts
import { initializeLicense } from '@worksheet-js/core';

export default defineNuxtPlugin(() => {
  initializeLicense('YOUR-LICENSE-KEY');
});

<!-- pages/spreadsheet.vue -->
<template>
  <ClientOnly>
    <div style="height: 600px;">
      <Worksheet :options="options" />
    </div>
  </ClientOnly>
</template>

<script setup lang="ts">
import { Worksheet } from '@worksheet-js/vue';

const options = {
  worksheets: [{ worksheetName: 'Sheet1' }],
  toolbar: true,
};
</script>

License

@worksheet-js/vue is open-source software released under the MIT License.

The underlying engine (@worksheet-js/core) is proprietary software subject to the EULA. A valid license key is required to use it.

Copyright © 2024-present Worksheet Systems.