1. Spreadsheet docs
  2. Developers

TypeScript

The TypeScript declarations that ship with 8sheets and its components, the types you will use, and the few places that are typed loosely.

@8sheets/core ships its declarations, generated from the source, so import { mountWorkbook } from '@8sheets/core' is typed with no setting, paths entry or @types package. The React, Vue and Angular components ship their own types, built on the core ones. Plain JavaScript projects get the same completions in editors that read declarations.

Typed in each framework

JavaScript

import { mountWorkbook, type SheetsWorkbook, type SheetRange } from '@8sheets/core';

type MountOptions = NonNullable<Parameters<typeof mountWorkbook>[1]>;
type StylePatch = SheetRange['style'];

const options: MountOptions = { chrome: 'light', parts: { titleBar: false } };
const header: StylePatch = { bold: true, fill: { theme: 'accent1' }, color: '#FFFFFF' };

const wb: SheetsWorkbook = await mountWorkbook(document.querySelector<HTMLElement>('#sheet')!, options);
wb.activeSheet.range('A1:D1').style = header;
wb.events.on('cells-changed', (e) => console.log(e.count));

React

import { useRef } from 'react';
import { Sheet, type SheetRef, type SheetOptions, type SheetsEvent } from '@8sheets/react';
import type { SheetsWorkbook } from '@8sheets/core';

const options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };

export function Budget() {
  const sheet = useRef<SheetRef>(null);
  const onReady = (wb: SheetsWorkbook) => { wb.activeSheet.range('A1').values = [['Item', 'Cost']]; };
  const onCells = (e: SheetsEvent) => console.log(e.count, sheet.current?.workbook?.activeSheet.name);
  return (
    <div style={{ height: 480 }}>
      <Sheet ref={sheet} options={options} onReady={onReady} onCellsChanged={onCells} />
    </div>
  );
}

Vue

<script setup lang="ts">
import { Sheet, useSheet, type SheetOptions, type SheetEventObject } from '@8sheets/vue';
import type { SheetsWorkbook } from '@8sheets/core';

const options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };
const { sheet, workbook } = useSheet();   // ShallowRef<SheetExposed | null>, ComputedRef<SheetsWorkbook | null>

function onReady(wb: SheetsWorkbook) {
  wb.activeSheet.range('A1').values = [['Item', 'Cost']];
}
function onCells(e: SheetEventObject) {
  console.log(e.count, workbook.value?.activeSheet.name);
}
</script>

<template>
  <Sheet ref="sheet" :options="options" style="height: 480px" @ready="onReady" @cells-changed="onCells" />
</template>

Angular

import { Component } from '@angular/core';
import { SheetComponent, type SheetEventPayload, type SheetOptions, type SheetsWorkbook } from '@8sheets/angular';
import type { SheetRange } from '@8sheets/core';

@Component({
  selector: 'app-budget',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" [options]="options" (ready)="onReady($event)" (cellsChanged)="onCells($event)" />`,
  styles: `.grid { height: 480px; }`,
})
export class Budget {
  options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };
  header: SheetRange['style'] = { bold: true, fill: { theme: 'accent1' } };

  onReady(wb: SheetsWorkbook) {
    wb.activeSheet.range('A1:B1').style = this.header;
  }

  onCells(e: SheetEventPayload) {
    console.log(e['count']);
  }
}

In Angular, import from @8sheets/core with import type only: the component loads the library at run time, and a value import would bundle a second copy.

The types you will use

FromTypes
@8sheets/coreSheetsWorkbook, SheetHandle (a sheet), SheetRange, SheetTable, SheetObject, SheetChart, SheetShape, SheetPivot, SheetSlicer, CommentThread, FunctionsApi, NamesApi, History, CommandManager, ThemeApi, UserDirectory, SheetPrint, SheetEvent
@8sheets/reactSheetProps, SheetRef, SheetOptions, SheetsEvent, SheetEventHandler
@8sheets/vueSheetOptions, SheetEventName, SheetEventObject, SheetExposed
@8sheets/angularSheetOptions, SheetsWorkbook, SheetEventPayload

The package exports only its entry point, so types declared inside it but not exported by name are reached through the classes that use them:

import type { SheetRange, SheetHandle, mountWorkbook } from '@8sheets/core';

type MountOptions = NonNullable<Parameters<typeof mountWorkbook>[1]>;   // parts, chrome, theme, …
type PartsOption = NonNullable<MountOptions['parts']>;
type StylePatch = SheetRange['style'];                                    // bold, fill, numFmt, …
type CellValue = SheetRange['values'][number][number];                    // number | string | boolean | Date | null
type TableOptions = NonNullable<Parameters<SheetHandle['addTable']>[1]>;
type ValidationRule = Parameters<SheetHandle['setValidation']>[1];

Where the types are loose

The declarations are generated from JSDoc in the source, and a few parts are typed broadly:

  • Event objects in wb.events.on(type, fn) are any, so their fields (count, cells(), sheet, text) aren't checked; event names are plain strings. The list of all events gives each event's fields. The component types are a little tighter: React's SheetsEvent and Vue's SheetEventObject declare type, workbook, cancelled and cancel(), and Vue's SheetEventName lists every event name.
  • Options beyond the mount options are Record<string, any>, so a misspelled option name passes the compiler. mountWorkbook and setOptions check every key at run time and throw a RangeError for an unknown one.
  • wb.statusBar, wb.nameBox and wb.settings are declared, as … | undefined, because only a mounted workbook has them: use wb.statusBar?.setMessage(…) or check them first.
  • sheet.charts and sheet.shapes give the raw records, typed loosely. Use sheet.chartHandles, sheet.shapeHandles, sheet.chart() and sheet.shape() for typed SheetChart and SheetShape handles.
  • Conditional formatting rules for addConditionalFormatRule are typed with type, operator, formulas and stopIfTrue only, so rules with other file-format fields, such as { type: 'top10', rank: 3 } or a colorScale, need a cast in TypeScript (as any, or a wider type of your own). They work at run time.
  • Cell type options are { type } & Record<string, any>: the type name is checked at run time (a RangeError for an unknown one), and the options are cleaned, not checked.
  • Rules in the file format's own shape passed to addValidation and addConditionalFormat are typed object. The newer setValidation and addConditionalFormatRule take typed rules, which you can name with Parameters<SheetHandle['setValidation']>[1].

Node projects

The declarations name DOM types such as HTMLElement, because the same API mounts in a page. A Node project that checks library types (skipLibCheck: false) needs "DOM" in lib; with skipLibCheck: true, the default in most templates, nothing is needed.