Vue 3 Integration

The @witqq/spreadsheet-vue package provides a WitTable component built with Vue 3 Composition API. It wraps the core canvas engine with Vue-friendly props, events, and an exposed API via template refs.

Installation

npm install @witqq/spreadsheet @witqq/spreadsheet-vue

Requires Vue 3.3+.

WitTable Component

<script setup lang="ts">
import { WitTable } from '@witqq/spreadsheet-vue';
import type { ColumnDef } from '@witqq/spreadsheet';

const columns: ColumnDef[] = [
  { key: 'name', title: 'Name', width: 180 },
  { key: 'email', title: 'Email', width: 220 },
];

const data = [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' },
];
</script>

<template>
  <WitTable :columns="columns" :data="data" />
</template>

Props

All props map directly to WitEngineConfig fields:

Prop	Type	Required	Description
`columns`	`ColumnDef[]`	Yes	Column definitions
`data`	`Record<string, unknown>[]`	No	Row data array
`rowCount`	`number`	No	Total row count (virtual scrolling)
`theme`	`WitTheme`	No	Theme object
`frozenRows`	`number`	No	Number of frozen rows
`frozenColumns`	`number`	No	Number of frozen columns
`editable`	`boolean`	No	Enable cell editing
`sortable`	`boolean`	No	Enable column sorting
`showGridLines`	`boolean`	No	Show grid lines
`showRowNumbers`	`boolean`	No	Show row numbers
`rowHeight`	`number`	No	Default row height (px)
`headerHeight`	`number`	No	Header row height (px)
`width`	`number \| string`	No	Container width
`height`	`number \| string`	No	Container height

Events

<WitTable
  :columns="columns"
  :data="data"
  @cell-change="onCellChange"
  @selection-change="onSelectionChange"
  @sort-change="onSortChange"
  @filter-change="onFilterChange"
  @scroll="onScroll"
  @ready="onReady"
/>

Event	Payload	Fires when
`cell-change`	`CellChangeEvent`	A cell value is edited
`selection-change`	`SelectionChangeEvent`	Active cell or selection range changes
`sort-change`	`SortChangeEvent`	Column sort is applied or cleared
`filter-change`	`FilterChangeEvent`	Filter is applied, changed, or removed
`scroll`	`ScrollEvent`	The viewport scrolls
`ready`	—	The engine is fully initialized

Template Ref (Exposed API)

Access the component’s imperative API via ref:

<script setup lang="ts">
import { ref } from 'vue';
import { WitTable } from '@witqq/spreadsheet-vue';
import type { WitTableExposed } from '@witqq/spreadsheet-vue';

const tableRef = ref<InstanceType<typeof WitTable> & WitTableExposed>();

function handleUndo() {
  tableRef.value?.undo();
}
</script>

<template>
  <WitTable ref="tableRef" :columns="columns" :data="data" />
  <button @click="handleUndo">Undo</button>
</template>

WitTableExposed Interface

interface WitTableExposed {
  getInstance(): WitEngine;
  focus(): void;
  getSelection(): Selection;
  selectCell(row: number, col: number): void;
  getCell(row: number, col: number): CellData | undefined;
  setCell(row: number, col: number, value: CellValue): void;
  undo(): void;
  redo(): void;
  scrollTo(x: number, y: number): void;
  requestRender(): void;
  installPlugin(plugin: WitPlugin): void;
  removePlugin(name: string): void;
  print(): void;
}

Method	Description
`getInstance()`	Access the underlying `WitEngine`
`focus()`	Focus the table container
`getSelection()`	Current selection state
`selectCell(row, col)`	Programmatically select a cell
`getCell(row, col)`	Read cell data
`setCell(row, col, value)`	Write a cell value
`undo() / redo()`	Command history navigation
`scrollTo(x, y)`	Scroll to pixel position
`requestRender()`	Force a canvas re-render
`installPlugin(plugin)`	Install a plugin at runtime
`removePlugin(name)`	Remove a plugin by name
`print()`	Trigger print layout

Reactive Watchers

The component watches two props and updates the engine automatically:

theme — calls engine.setTheme() when the theme object changes
data — clears the cell store, bulk-loads the new data, updates row count, and re-renders

<script setup lang="ts">
import { ref } from 'vue';
import { lightTheme, darkTheme } from '@witqq/spreadsheet';

const isDark = ref(false);
const currentTheme = computed(() => isDark.value ? darkTheme : lightTheme);
const rows = ref(initialData);
</script>

<template>
  <WitTable :columns="columns" :data="rows" :theme="currentTheme" />
  <button @click="isDark = !isDark">Toggle theme</button>
</template>

Plugin Installation

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { WitTable } from '@witqq/spreadsheet-vue';
import type { WitTableExposed } from '@witqq/spreadsheet-vue';
import { FormulaPlugin, ExcelPlugin } from '@witqq/spreadsheet-plugins';

const tableRef = ref<InstanceType<typeof WitTable> & WitTableExposed>();

onMounted(() => {
  tableRef.value?.installPlugin(new FormulaPlugin());
  tableRef.value?.installPlugin(new ExcelPlugin());
});

onUnmounted(() => {
  tableRef.value?.removePlugin('formula');
  tableRef.value?.removePlugin('excel');
});
</script>

<template>
  <WitTable ref="tableRef" :columns="columns" :data="data" />
</template>

TypeScript

The component is fully typed. Import types from @witqq/spreadsheet:

import type {
  ColumnDef,
  CellData,
  CellValue,
  Selection,
  WitTheme,
  WitPlugin,
  CellChangeEvent,
  SelectionChangeEvent,
  SortChangeEvent,
  FilterChangeEvent,
  ScrollEvent,
} from '@witqq/spreadsheet';