- Spreadsheet docs
- Developers
Themes and skins
Match the spreadsheet to your product with chrome skins and your own colours, and set the workbook theme that colours cells, charts and tables.
Two separate things decide how an embedded workbook looks:
- The chrome is the app around the cells: ribbon, formula bar, tabs, headers, menus, dialogs and the status bar. It is a setting of your page, not of the file. Use it to fit the spreadsheet into your product's design and its light or dark mode.
- The workbook theme is part of the file: the colours and fonts that cells, charts, tables and shapes refer to, as in Excel. Changing it changes the document, can be undone, and is saved in the
.xlsx.
Cells stay white on a dark chrome, as in desktop spreadsheets, because their colours belong to the document.
Match your product
JavaScript
import { mountWorkbook } from '@8sheets/core';
const brand = {
base: 'light',
tokens: { accent: '#4f46e5', 'accent-ink': '#3730a3', chrome: '#f8fafc', bar: '#f8fafc' },
grid: { headerBg: '#f1f5f9', headerActiveBg: '#e0e7ff', headerActiveInk: '#3730a3', selectionFill: 'rgba(79, 70, 229, 0.12)' },
titleBar: { background: '#4f46e5', color: '#ffffff' },
};
const wb = await mountWorkbook(document.querySelector('#sheet'), { chrome: brand, theme: 'Fjord' });
// Follow your app's own dark mode switch.
const media = matchMedia('(prefers-color-scheme: dark)');
media.addEventListener('change', () => wb.setOptions({ chrome: media.matches ? 'slate' : brand }));React
import { Sheet } from '@8sheets/react';
const brand = {
base: 'light',
tokens: { accent: '#4f46e5', 'accent-ink': '#3730a3', chrome: '#f8fafc', bar: '#f8fafc' },
grid: { headerBg: '#f1f5f9', headerActiveBg: '#e0e7ff', headerActiveInk: '#3730a3', selectionFill: 'rgba(79, 70, 229, 0.12)' },
titleBar: { background: '#4f46e5', color: '#ffffff' },
};
export function Workbook({ dark }) {
return (
<div style={{ height: 560 }}>
<Sheet options={{ chrome: dark ? 'slate' : brand, theme: 'Fjord' }} />
</div>
);
}Vue
<script setup>
import { computed } from 'vue';
import { Sheet } from '@8sheets/vue';
const props = defineProps({ dark: Boolean });
const brand = {
base: 'light',
tokens: { accent: '#4f46e5', 'accent-ink': '#3730a3', chrome: '#f8fafc', bar: '#f8fafc' },
grid: { headerBg: '#f1f5f9', headerActiveBg: '#e0e7ff', headerActiveInk: '#3730a3', selectionFill: 'rgba(79, 70, 229, 0.12)' },
titleBar: { background: '#4f46e5', color: '#ffffff' },
};
const options = computed(() => ({ chrome: props.dark ? 'slate' : brand, theme: 'Fjord' }));
</script>
<template>
<Sheet :options="options" style="height: 560px" />
</template>Angular
import { Component, Input } from '@angular/core';
import { SheetComponent, SheetOptions } from '@8sheets/angular';
const brand = {
base: 'light' as const,
tokens: { accent: '#4f46e5', 'accent-ink': '#3730a3', chrome: '#f8fafc', bar: '#f8fafc' },
grid: { headerBg: '#f1f5f9', headerActiveBg: '#e0e7ff', headerActiveInk: '#3730a3', selectionFill: 'rgba(79, 70, 229, 0.12)' },
titleBar: { background: '#4f46e5', color: '#ffffff' },
};
@Component({
selector: 'app-workbook',
imports: [SheetComponent],
template: `<eight-sheet class="grid" [options]="options" />`,
styles: `.grid { height: 560px; }`,
})
export class Workbook {
options: SheetOptions = { chrome: brand, theme: 'Fjord' };
@Input() set dark(on: boolean) {
this.options = { ...this.options, chrome: on ? 'slate' : brand };
}
}The components pass a changed chrome to wb.setOptions, so switching skins doesn't remount the workbook. theme given in options is applied as an undo step; a value equal to the last one changes nothing.
Chrome
chrome is an option of mountWorkbook and setOptions, and also wb.theme.chrome:
| Value | Look |
|---|---|
'auto' (default) | Light or dark, following the system |
'light', 'dark' | Fixed light or dark |
'white', 'light-gray', 'dark-gray', 'colorful' | Light skins, from all white to a coloured title bar and headers |
'black', 'slate' | Dark skins |
{ base, tokens, grid, titleBar } | Your own skin |
A skin of your own starts from base (light or dark) and overrides colours in three groups:
| Group | Keys | Colours |
|---|---|---|
tokens | chrome, panel, panel-line, bar, bar-line, menu, field, field-line, ink, ink-soft, hover, accent, accent-ink, sheet-active-bg, sheet-active-ink | The app's surfaces, lines, text and accent: the ribbon background, panes, bars, menus, input fields and the active sheet tab |
grid | headerBg, headerInk, headerLine, headerActiveBg, headerActiveInk, headerFullBg, accent, selectionFill | Row and column headers, the headers of the selection, and the selection |
titleBar | background, color | The title bar |
Each value is a CSS colour string. A bad value throws a RangeError before anything changes. Each workbook on a page keeps its own chrome, and dialogs and menus open in the colours of the workbook in use. wb.theme.skins lists the named skins.
The chrome respects the system's high-contrast, forced-colours and reduced-motion settings.
Interface size and ribbon layout
Three options fit the app's chrome to the pages around it. All of them work in mountWorkbook and setOptions.
| Option | Default | Effect |
|---|---|---|
uiScale | null | Size of the interface around the cells, from 0.75 to 2: the text, icons and bars of the title bar, ribbon, formula bar, sheet tabs, status bar and task panes, and the menus and dialogs. 1 is the usual size and 1.25 a quarter larger. The cells keep their own zoom. null uses the size the user picked under View > Interface Size, else 1. |
ribbonLayout | null | 'simplified': one row of icons, with groups that don't fit behind a More button. 'classic': Excel's full ribbon with big buttons and labels. null uses the layout the user last picked with the button at the end of the ribbon, else 'simplified'. |
miniToolbar | true | The mini toolbar over the menu that a right click on cells opens. false shows the menu alone. |
const wb = await mountWorkbook(host, { uiScale: 0.9, ribbonLayout: 'classic' });
wb.setOptions({ uiScale: 1.25 }); // larger text and icons in a roomier page
The size uses CSS zoom, which current versions of Chrome, Edge, Firefox and Safari support. Each workbook on a page keeps its own size; its menus and dialogs open at that size.
Workbook theme
The workbook theme is what Excel calls the document theme: twelve colour slots (dk1, lt1, dk2, lt2, accent1 to accent6, hlink, folHlink) and a heading and body font. Cell styles, charts, tables and shapes that refer to a slot change with it.
wb.theme.apply('Lagoon'); // a theme from the gallery: colours and fonts
wb.theme.setColors('Tide'); // only the colours, from a named colour set
wb.theme.setFonts({ major: 'Georgia', minor: 'Verdana' }); // only the fonts
wb.theme.apply(wb.theme.build({ name: 'Acme', colors: { accent1: '#4f46e5', accent2: '#0ea5e9' } }));
wb.theme.gallery; // the themes of the gallery
wb.theme.colorSets; // the named colour sets
wb.theme.fontSets; // the named font pairs
wb.theme.current; // the theme in use
The gallery has themes such as Aurora, Basalt, Canyon, Citrus, Coral, Dune, Ember, Fjord, Glacier, Graphite, Harbor, Ink, Lagoon, Meadow, Moss, Mulberry, Orchard, Plum, Saffron and Terracotta, besides the defaults new workbooks use. wb.theme.build(spec) checks a theme without applying it, and wb.theme.fromXml(xml) loads one from a theme1.xml taken from another file; wb.theme.toXml() gives the XML the workbook saves.
To use a theme colour in a cell, give the slot and an optional tint from -1 (darker) to 1 (lighter):
sheet.range('A1:F1').style = { fill: { theme: 'accent1' }, color: { theme: 'lt1' } };
sheet.range('A2:F2').style = { fill: { theme: 'accent1', tint: 0.8 } };
Each theme change is one undo step and fires theme-changed.
Fonts
Fonts named in a workbook are drawn with the fonts installed on the user's device, with a fallback when one is missing. The defaultFont option sets the font of a new workbook, such as { name: 'Arial', size: 11 }.
Background and focus colours
| Option | Effect |
|---|---|
background | The background colour of the cell area. |
backgroundImage, backgroundImageFit | A picture behind the cells of every sheet, as a data URL; it saves as the sheet background. |
emptyAreaColor | The colour beyond the last row and column. |
focusHighlight | Highlights the row and column of the active cell: { color, colColor, alpha }. |
copyIndicatorColor | The colour of the moving border around copied cells. |
tabStyles | The default look of sheet tabs: { color, background, activeColor, activeBackground, font }. |