Theme Customization

Customize Handsontable's appearance using the Theme API, Figma Theme Generator, CSS variables, or the visual Theme Builder.

[[toc]]

Overview

CSS variables provide a powerful and flexible way to customize Handsontable's appearance by adjusting design elements such as colors, spacing, borders, and typography to match your application's design system. These variables give you granular control over every visual aspect of the data grid, from basic styling to advanced component customization.

We provide multiple approaches for leveraging CSS variables to create any look that your designer can imagine. From quick theme modifications to completely custom designs, your options include:

1. Theme API – Modify themes via configuration parameters or register your own custom theme programmatically.
2. Figma Theme Generator – Modify design variables in Figma and export them using the Figma Theme Generator tool.
3. Override CSS variables – Directly override CSS variables or edit CSS files from the /styles directory for full control.
4. Theme Builder UI – Use the online Theme Builder to visually customize and export your theme without writing code.

The data grid's styling system is built entirely on CSS variables, with over 200 variables organized into logical categories covering typography, colors, spacing, borders, and component-specific styling listed below.

Option 1: Theme API

The Theme API allows you to customize themes programmatically by registering custom themes and configuring them at runtime. You can use the theme option with a ThemeBuilder object for dynamic configuration.

Register a custom theme

Use registerTheme to create a custom theme with your own configuration:

::: only-for javascript

import Handsontable from 'handsontable';

import { mainTheme, registerTheme } from 'handsontable/themes';

// Register main theme
const myTheme = registerTheme(mainTheme);

// Configure the theme at runtime
myTheme.setColorScheme('light'); // 'light', 'dark', or 'auto'
myTheme.setDensityType('default'); // 'compact', 'default', or 'comfortable'

const hot = new Handsontable(container, {
  theme: myTheme,
  // other options
});

:::

::: only-for react

import Handsontable from 'handsontable';
import { HotTable } from '@handsontable/react-wrapper';

import { mainTheme, registerTheme } from 'handsontable/themes';

// Register main theme
const myTheme = registerTheme(mainTheme);

// Configure the theme at runtime
myTheme.setColorScheme('light');
myTheme.setDensityType('default');

function App() {
  return (
    <HotTable
      theme={myTheme}
      // other options
    />
  );
}

:::

::: only-for angular

import Handsontable from 'handsontable';

import { mainTheme, registerTheme } from 'handsontable/themes';

// Register main theme
const myTheme = registerTheme(mainTheme);

// Configure the theme at runtime
myTheme.setColorScheme('light');
myTheme.setDensityType('default');

<hot-table [theme]="myTheme">
</hot-table>

:::

Configure theme parameters

Use the params() method to update theme parameters dynamically:

myTheme.params({
  colors: {
    primary: {
      500: '#9333ea', // Change primary color
    },
  },
  tokens: {
    fontSize: '16px',
    iconSize: 'sizing.size_5',
    borderColor: ['colors.primary.500', 'colors.primary.600'],
  },
});

Theme API example

The following example demonstrates using the Theme API to register a theme with a custom purple accent color:

::: only-for javascript

::: example #example2 --html 1 --js 2 --ts 3 @code @code @code :::

:::

::: only-for react

::: example #example2 .disable-auto-theme :react --js 1 --ts 2 @code @code :::

:::

::: only-for angular

::: example #example2 :angular --ts 1 --html 2 @code @code :::

:::

Option 2: Figma Theme Generator

The Figma Theme Generator allows designers and developers to work together seamlessly by exporting design tokens directly from Figma into a CSS theme file.

Export themes from Figma

To create a new theme or modify an existing one in Figma:

1. Open your Figma design file and modify the design variables (colors, spacing, typography, etc.) to match your requirements.
2. Export the design tokens as JSON using Figma's built-in variables export or a plugin.
3. Visit the Handsontable Theme Generator and follow the instructions to convert your Figma tokens into CSS theme files or JS variable objects.

The Theme Generator transforms JSON tokens exported from Figma into properly formatted theme files that work with Handsontable. It outputs CSS files (with or without icons) and JS variable files for colors, tokens, and icons. This approach is ideal for teams where designers define the visual language in Figma and developers implement it in code.

Option 3: Override CSS variables

For full control over your theme, you can override CSS variables directly. Follow these steps to apply a theme, then override the variables for your chosen theme.

You can also directly modify the CSS theme files located in handsontable/dist/styles/themes/. This gives you immediate access to all CSS variables and allows for quick iterations.

Here's an example for .ht-theme-main:

::: only-for javascript

::: example #example1 --html 1 --js 2 --ts 3 @code @code @code :::

:::

::: only-for react

::: example #example1 .disable-auto-theme :react --js 1 --ts 2 @code @code :::

:::

::: only-for angular

::: example #example1 :angular --ts 1 --html 2 @code @code :::

:::

Option 4: Use the Theme Builder UI

If you prefer a visual approach to creating themes, use the Handsontable Theme Builder. This online tool provides an intuitive interface for customizing colors, spacing, and other theme properties without writing code. Once you're satisfied with your design, you can export the generated your theme and integrate it into your project.

Variables Reference

Handsontable provides a comprehensive set of JS and CSS variables that let you customize the appearance of every component.

CSS Variable — The names of the CSS custom properties (e.g. --ht-sizing-size-1) you can override in your stylesheet.

JS Option — The values in this column are the keys you use when customizing a theme via the Theme API. Call theme.params() on your registered theme and pass an object where each key is nested under one of:

• sizing — spacing and size scale (e.g. sizing.size_1)
• density.sizes.default, density.sizes.compact, or density.sizes.comfortable — density-specific spacing (e.g. cellVertical, gap)
• colors — color palette (e.g. colors.primary.500)
• tokens — design tokens used by components (e.g. tokens.fontSize)

Example: to override the tokens.gapSize, use the JS Option like this:

  myTheme.params({
    tokens: {
      gapSize: 'sizing.size_1'
    }
  })

Sizing Variables

Density Variables

Color Palette Variables

Tokens Variables

Typography Variables

Layout & Spacing Variables

Color System Variables

Shadow Variables

Bar Variables

Cell Border Variables

Wrapper Variables

Row Styling Variables

Cell Padding Variables

Cell Editor Variables

Cell State Variables

Cell Selection Variables

Cell Autofill Variables

Cell Mobile Handle Variables

Indicator Variables

Scrollbar Variables

Header Variables

Header Row Variables

Checkbox Variables

Radio Button Variables

Icon Button Variables

Collapse Button Variables

Button Variables

Primary Button Variables

Secondary Button Variables

Chip Variables

Comments Variables

License Variables

Link Variables

Input Variables

Menu Variables

Dialog Variables

Notification Variables

These variables style the Notification plugin toasts. Shared layout tokens (for example wrapperBorderRadius, tableTransition, gapSize) and icon-button tokens still apply to the close control and spacing.

Pagination Variables

Related blog articles

• From components to tables: Designing a data table component in your design system
• Handsontable 14.6.0: Easier styling and enhanced undo-redo