JavaScript Data Grid Themes

JavaScript Data GridThemes

Use Handsontable's built-in themes or customize its look using the Theme API or CSS variables.

On this page

Overview

Handsontable themes manage most visual elements of the data grid. Three built-in themes are available: main, horizon, and classic. All themes include dark and light modes.

The recommended way to apply themes is using the Theme API, which allows you to register and configure themes programmatically with runtime features like density modes and color schemes. Alternatively, you can use CSS files and pass the theme name as a string for a simpler setup.

Built-in themes

The main theme offers a spreadsheet-like interface, perfect for batch-editing tasks and providing users with a familiar experience, similar to other popular spreadsheet software on the market.

The horizon theme, on the other hand, is better suited for data display and analysis. It hides the vertical lines between columns, giving it a cleaner and more lightweight feel.

The classic theme is a replacement for the old legacy style. It retains the familiar look and feel of the original legacy styles, but has been updated to allow customization with CSS variables. This theme is ideal for users who prefer the traditional appearance of Handsontable but want to benefit from the theming system. The classic theme supports both light and dark modes, ensuring a seamless integration with your application's color scheme preferences.

Keep in mind that starting from version 15.0, importing a theme is required.

Default theme

If you want to use the main theme without any modifications, you don't need to configure anything. Handsontable will automatically use the main theme with default settings.

    Light and dark modes

    Each theme comes with three modes:

    • Light mode
    • Dark mode
    • Auto mode

    When using the Theme API, you can configure the color scheme using setColorScheme() with 'light', 'dark', or 'auto' values. The 'auto' option allows programmatic control over light/dark switching based on your application's logic.

    When using CSS files, color scheme switching is controlled through CSS class names. Use ht-theme-{name} for light mode, ht-theme-{name}-dark for dark mode, or ht-theme-{name}-dark-auto for automatic switching based on system preferences (e.g., ht-theme-main, ht-theme-main-dark, ht-theme-main-dark-auto).

    Available Theme API parameters

    When registering a theme with registerTheme() or updating it using the params() method, you can configure the following keys:

    Key Description
    name Theme name string (can only be set during registerTheme(), cannot be updated via params())
    sizing Size scale values (size_0 through size_10)
    density Density type ('default', 'compact', 'comfortable') or density configuration object
    icons SVG icon definitions
    colors Color palette with nested color values
    tokens Design tokens for visual properties
    colorScheme Color scheme ('light', 'dark', or 'auto')

    Token value references

    Token values support a powerful reference system using dot notation. Instead of hardcoding values, you can reference values from other configuration namespaces:

    Reference pattern Example Description
    Direct value '14px' Use a literal CSS value
    tokens.* 'tokens.foregroundColor' Reference another token value
    sizing.* 'sizing.size_4' Reference a sizing scale value
    colors.* 'colors.primary.500' Reference a color from the palette
    density.* 'density.gap' Reference a density-specific value

    Sizing references

    The sizing scale provides consistent spacing values:

    myTheme.params({
  tokens: {
    iconSize: 'sizing.size_5',             // References e.g. 20px
    wrapperBorderRadius: 'sizing.size_2',  // References e.g. 8px
  },
});

    Color references

    Colors use a hierarchical structure with dot notation for nested values:

    myTheme.params({
  tokens: {
    accentColor: 'colors.primary.500',      // References primary color
    borderColor: 'colors.palette.200',      // References palette color
    backgroundColor: 'colors.white',        // References base white color
  },
});

    Density references

    Density values adjust spacing based on the selected density type:

    myTheme.params({
  tokens: {
    cellHorizontalPadding: 'density.cellHorizontal',
    buttonVerticalPadding: 'density.buttonVertical',
    gapSize: 'density.gap',
  },
});

    Token cross-references

    Tokens can reference other tokens for consistent styling:

    myTheme.params({
  tokens: {
    barForegroundColor: 'tokens.foregroundColor',
    cellEditorBackgroundColor: 'tokens.backgroundColor',
  },
});

    Light and dark mode values

    For tokens that should have different values in light and dark modes, use an array with two values where the first value is for light mode and the second is for dark mode:

    myTheme.params({
  tokens: {
    // [lightModeValue, darkModeValue]
    borderColor: ['colors.palette.100', 'colors.palette.700'],
    foregroundColor: ['colors.palette.800', 'colors.palette.200'],
    backgroundColor: ['colors.white', 'colors.palette.950'],
  },
});

    Available CSS files

    Handsontable provides CSS files needed to style your data grid. Here's an overview of what's available:

    Base CSS file

    • handsontable.css / handsontable.min.css - The base stylesheet containing all structural styles, layout rules, and core functionality. This file is auto-injected by default. You can inject it manually instead, but you must set injectCoreCss to false first. It includes border styles, cell rendering rules, and other fundamental grid components.

    Theme files

    All themes are available in two variants:

    • ht-theme-{name}.css / ht-theme-{name}.min.css - Complete theme with icons included (where {name} is main, horizon, or classic).
    • ht-theme-{name}-no-icons.css / ht-theme-{name}-no-icons.min.css - Theme without icon styles.

    Icon files

    If you're using a theme without icons (*-no-icons.css), you can optionally load separate icon files:

    • ht-icons-{name}.css / ht-icons-{name}.min.css - Icon styles for the theme (where {name} is main or horizon).

    For production, use the minified versions (.min.css) to reduce file size and improve load times. For development, you may prefer the unminified versions (.css) for easier debugging.

    Use a theme

    There are two ways to apply a theme. The recommended approach is to use the Theme API with a theme object, which provides full access to runtime configuration features like density modes and color schemes.

    The Theme API allows you to import and register themes programmatically. This approach provides runtime access to theme customization features.

    Import and use theme

    import Handsontable from 'handsontable';
import { classicTheme } from 'handsontable/themes';

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

    You can configure the theme before creating the instance using the builder pattern:

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

const theme = registerTheme(mainTheme)
  .setColorScheme('auto')   // 'light', 'dark', or 'auto'
  .setDensityType('comfortable');  // 'default', 'compact', or 'comfortable'

const hot = new Handsontable(container, {
  theme,
});

    Or configure it after init by retrieving the registered theme with getTheme() (the theme is registered when you pass it to the config):

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

const hot = new Handsontable(container, {
  theme: mainTheme,
});

getTheme('main')
  ?.setColorScheme('auto')
  ?.setDensityType('comfortable');

    UMD build (script tags)

    When using Handsontable via CDN or script tags, load the theme script after the main Handsontable script. The theme auto-registers itself, and you can retrieve it using getTheme():

    <script src="https://cdn.jsdelivr.net/npm/handsontable/dist/handsontable.full.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/handsontable/dist/themes/main.min.js"></script>

<script>
  // The theme is auto-registered when the script loads
  // Retrieve it using getTheme()
  const theme = Handsontable.themes.getTheme('main')
    .setColorScheme('auto')
    .setDensityType('default');

  const hot = new Handsontable(document.getElementById('container'), {
    theme: theme,
    // ... other options
  });
</script>

    Option 2: Using CSS files

    Alternatively, you can load theme CSS files and pass the theme name as a string to the theme option.

    Step 1. Load CSS files

    To ensure Handsontable renders correctly, it's required to load both the base and theme CSS files. The base file contains structural styles, while the theme file includes colors, sizes, and other variables needed for the grid.

    // ESM (ECMAScript modules)
import 'handsontable/styles/ht-theme-main.min.css';

// CommonJS
require('handsontable/styles/ht-theme-main.min.css');

    Alternatively, you can import the necessary files from the recommended CDN such as JSDelivr (opens new window) or cdnjs (opens new window).

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-main.min.css" />

    Step 2. Pass a theme name

    To use a theme, specify the theme name in the data grid's global settings object:

    const container = document.querySelector('#handsontable-example');

const hot = new Handsontable(container, {
  // theme name with obligatory `ht-theme-*` prefix
  theme: 'ht-theme-main',
  // other options
});

    The legacy theme

    The legacy CSS file (handsontable.full.min.css (opens new window)) was the default styles up until version 15 (released in December 2024). These styles are legacy and are removed in version 17.0.0.

    Known limitations

    In some cases, global styles enforced by the browser or operating system can impact the appearance of the data grid. This is a common challenge faced by all websites, not just Handsontable. Here are two specific scenarios and how to handle them:

    • High contrast mode in Windows: To style the component when Windows' high contrast mode is active, use the forced-colors media query. This allows you to detect and adapt to forced color settings. Read more (opens new window)
    • Auto dark theme in Google Chrome: Chrome automatically applies a dark theme in some scenarios. To detect and manage this behavior, refer to the official Chrome guide (opens new window)

    Troubleshooting

    Didn't find what you need? Try this: