1. Spreadsheet docs
  2. Developers

Cell types

Put checkboxes, buttons, option lists, dropdowns, links, progress bars and file uploads inside cells, run your own code from cell buttons, and register your own cell types.

A cell type draws a control inside a cell and lets people use it with the mouse or the keyboard: a checkbox for a done flag, a button that runs your code, a list of options, a progress bar, a link, a file upload. The cell keeps an ordinary value underneath, so formulas, sorting, filtering and copying work as with any cell: a checkbox holds TRUE or FALSE, an option list holds the chosen item.

Add controls to cells

JavaScript

import { mountWorkbook, registerButtonAction } from '@8sheets/core';

const wb = await mountWorkbook(document.querySelector('#sheet'));
const sheet = wb.activeSheet;
sheet.range('A1').values = [['Task', 'Done', 'Priority', 'Progress', ''], ['Write the spec', false, 'High', 40, null]];

sheet.range('B2:B20').cellType = { type: 'checkbox', text: 'Done' };
sheet.range('C2:C20').cellType = { type: 'combobox', items: ['High', 'Medium', 'Low'] };
sheet.range('D2:D20').cellType = { type: 'progress', min: 0, max: 100 };
sheet.range('E2:E20').cellType = { type: 'button', text: 'Approve', action: 'approve' };

// A button runs a named action: a file only stores the name, never code.
registerButtonAction('approve', ({ sheet, row }) => {
  sheet.cell(row, 3).values = 100;
  sheet.cell(row, 1).values = true;
});

React

import { registerButtonAction } from '@8sheets/core';
import { Sheet } from '@8sheets/react';

registerButtonAction('approve', ({ sheet, row }) => {
  sheet.cell(row, 3).values = 100;
  sheet.cell(row, 1).values = true;
});

function addControls(wb) {
  const sheet = wb.activeSheet;
  sheet.range('B2:B20').cellType = { type: 'checkbox', text: 'Done' };
  sheet.range('C2:C20').cellType = { type: 'combobox', items: ['High', 'Medium', 'Low'] };
  sheet.range('D2:D20').cellType = { type: 'progress', min: 0, max: 100 };
  sheet.range('E2:E20').cellType = { type: 'button', text: 'Approve', action: 'approve' };
}

export function Tasks() {
  return <div style={{ height: 480 }}><Sheet onReady={addControls} /></div>;
}

Vue

<script setup>
import { registerButtonAction } from '@8sheets/core';
import { Sheet } from '@8sheets/vue';

registerButtonAction('approve', ({ sheet, row }) => {
  sheet.cell(row, 3).values = 100;
  sheet.cell(row, 1).values = true;
});

function addControls(wb) {
  const sheet = wb.activeSheet;
  sheet.range('B2:B20').cellType = { type: 'checkbox', text: 'Done' };
  sheet.range('C2:C20').cellType = { type: 'combobox', items: ['High', 'Medium', 'Low'] };
  sheet.range('D2:D20').cellType = { type: 'progress', min: 0, max: 100 };
  sheet.range('E2:E20').cellType = { type: 'button', text: 'Approve', action: 'approve' };
}
</script>

<template>
  <Sheet style="height: 480px" @ready="addControls" />
</template>

Angular

import { Component, inject } from '@angular/core';
import { EIGHT_SHEETS_URL, SheetComponent, SheetsWorkbook } from '@8sheets/angular';
import type * as EightSheets from '@8sheets/core';

@Component({
  selector: 'app-tasks',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" (ready)="addControls($event)" />`,
  styles: `.grid { height: 480px; }`,
})
export class Tasks {
  private readonly apiUrl = inject(EIGHT_SHEETS_URL);

  async addControls(wb: SheetsWorkbook) {
    // The same module the component loaded, so registrations reach its workbooks.
    const api: typeof EightSheets = await import(/* @vite-ignore */ new URL(this.apiUrl, document.baseURI).href);
    api.registerButtonAction('approve', ({ sheet, row }) => {
      sheet.cell(row, 3).values = 100;
      sheet.cell(row, 1).values = true;
    });
    const sheet = wb.activeSheet;
    sheet.range('B2:B20').cellType = { type: 'checkbox', text: 'Done' };
    sheet.range('E2:E20').cellType = { type: 'button', text: 'Approve', action: 'approve' };
  }
}

In Angular, registerButtonAction, registerCellType and the other values of @8sheets/core come from the copy the component loads at run time: import it by the same URL, as above, so there is one copy of the module on the page.

Set, read and clear

sheet.range('B2:B20').cellType = { type: 'checkbox', text: 'Done' };   // one undo step
sheet.range('B2').cellType;                  // { type: 'checkbox', text: 'Done' }, or null for a plain cell
sheet.range('B2:B20').setCellType({ type: 'checkbox', mode: 'toggle' });   // the same, returning whether anything changed
sheet.range('B2:B20').cellType = null;       // plain cells again; the values stay

An unknown type throws a RangeError. Whole rows and columns stop at the used range. Options are cleaned as the app cleans a file's: unknown and unsafe ones are dropped.

The built-in types

CELL_TYPES lists them, and cellTypeNames() adds the types registered on the page.

TypeWhat it showsMain options
checkboxA box or a switch; the value is TRUE, FALSE or emptytext, textTrue, textFalse, mode (modern, toggle), threeState, textSide
buttonA push button that writes a value or runs an actiontext, value, action, color, disabled
radioOption buttons; the value is the chosen itemitems, horizontal
checklistSeveral boxes; the value lists the ticked itemsitems, separator
buttonlistA row of toggle buttonsitems, multiple, selectedColor
comboboxA dropdown listitems, or source (a range, a table, or a formula such as =SORT(UNIQUE(A2:A99))), editable
hyperlinkA linkurl, location, text, tooltip, action
progressA bar from the cell's numbermin, max, color, hideText
diagonalA header cell split diagonally, with several labelsdirection, color, lineStyle
fileA file kept inside the workbook; the value is its nameaccept, maxSize, preview, download
dataobjectA record held as JSON, shown through a templateproperty, template, format
rangeA small range of another sheet drawn as a templatesource, bindings

items are strings or { text, value, image, color, ink, disabled }. The full list of options, with keyboard behaviour, is in src/celltypes/README.md in the source download.

Button actions

registerButtonAction(name, fn) names code that buttons may run: a button cell type's action, a hyperlink with an action, and buttons in a cell's edge. fn gets { workbook, sheet, row, col, action }. A file stores only the name, so opening a workbook can never run anything your page didn't register.

Your own cell types

registerCellType(name, spec) adds a type that range.cellType = { type: name, … } can then use. It draws through paint(ctx, rect, value, style, scale, info) on the grid's canvas, in device pixels, and may add hitTest, activate (what a click or Space does), editText, parseEdit, fitWidth and toJSON. A class works too.

import { registerCellType } from '@8sheets/core';

registerCellType('stars', {
  paint(ctx, rect, value, style, scale) {
    const n = Math.max(0, Math.min(5, Number(value) || 0));
    ctx.font = `${12 * scale}px sans-serif`;
    ctx.fillStyle = '#d97706';
    ctx.fillText('★'.repeat(n) + '☆'.repeat(5 - n), rect.x + 4 * scale, rect.y + rect.h / 2 + 4 * scale);
    return false;   // true would also draw the plain value
  },
});
sheet.range('F2:F20').cellType = { type: 'stars' };

A failure in a hook is logged once and the cell shows its plain value. Names can't be those of built-in types.

In files

Cell types are saved in .xlsx (in a custom XML part that Excel keeps and ignores; Excel shows the plain values), in .8sh and in JSON. A file whose cells use a type this page hasn't registered keeps their settings across a save and shows the plain values; registering the type later brings them to life.

Limits

  • Controls refuse to write over a formula, into a locked cell of a protected sheet, and against a stopping data validation rule.
  • Links open only http, https and mailto addresses, and pictures in options are embedded data: URLs only, so a workbook can't make the page fetch anything.
  • A file cell holds at most 10 MB, and a workbook at most 256 MB of such files.
  • Registrations (registerButtonAction, registerCellType) belong to the page and apply to every workbook on it.
  • In the app, users add cell types with the Cell Type button on the ribbon.