1. Spreadsheet docs
  2. 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:

ValueLook
'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:

GroupKeysColours
tokenschrome, panel, panel-line, bar, bar-line, menu, field, field-line, ink, ink-soft, hover, accent, accent-ink, sheet-active-bg, sheet-active-inkThe app's surfaces, lines, text and accent: the ribbon background, panes, bars, menus, input fields and the active sheet tab
gridheaderBg, headerInk, headerLine, headerActiveBg, headerActiveInk, headerFullBg, accent, selectionFillRow and column headers, the headers of the selection, and the selection
titleBarbackground, colorThe 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.

OptionDefaultEffect
uiScalenullSize 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.
ribbonLayoutnull'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'.
miniToolbartrueThe 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

OptionEffect
backgroundThe background colour of the cell area.
backgroundImage, backgroundImageFitA picture behind the cells of every sheet, as a data URL; it saves as the sheet background.
emptyAreaColorThe colour beyond the last row and column.
focusHighlightHighlights the row and column of the active cell: { color, colColor, alpha }.
copyIndicatorColorThe colour of the moving border around copied cells.
tabStylesThe default look of sheet tabs: { color, background, activeColor, activeBackground, font }.