- Spreadsheet docs
- 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.
| Type | What it shows | Main options |
|---|---|---|
checkbox | A box or a switch; the value is TRUE, FALSE or empty | text, textTrue, textFalse, mode (modern, toggle), threeState, textSide |
button | A push button that writes a value or runs an action | text, value, action, color, disabled |
radio | Option buttons; the value is the chosen item | items, horizontal |
checklist | Several boxes; the value lists the ticked items | items, separator |
buttonlist | A row of toggle buttons | items, multiple, selectedColor |
combobox | A dropdown list | items, or source (a range, a table, or a formula such as =SORT(UNIQUE(A2:A99))), editable |
hyperlink | A link | url, location, text, tooltip, action |
progress | A bar from the cell's number | min, max, color, hideText |
diagonal | A header cell split diagonally, with several labels | direction, color, lineStyle |
file | A file kept inside the workbook; the value is its name | accept, maxSize, preview, download |
dataobject | A record held as JSON, shown through a template | property, template, format |
range | A small range of another sheet drawn as a template | source, 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,httpsandmailtoaddresses, and pictures in options are embeddeddata: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.