Angular Data Grid Themes

Angular 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 { mainTheme, registerTheme } from 'handsontable/themes';

const theme = registerTheme(mainTheme)
  .setColorScheme('auto')
  .setDensityType('comfortable');

// In your component
@Component({
  template: `<hot-table [settings]="hotSettings"></hot-table>`
})
export class AppComponent {
  hotSettings = {
    theme: theme,
    // ... other options
  };
}

    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');

    The recommended approach for applying global styles is to include them in the styles array defined in the angular.json configuration file.

    {
  // ...
  "styles": [
    "src/styles.css",
    "node_modules/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:

    <hot-table [settings]="{
  theme: 'ht-theme-main'
}">
</hot-table>

    Global Theme Management

    In addition to passing a theme via the settings object for individual Handsontable instances, you can set a global default theme that applies to all instances. This can be accomplished in two ways:

    Using ApplicationConfig

    You can use ApplicationConfig to provide a global configuration via the HOT_GLOBAL_CONFIG injection token.

    import { bootstrapApplication } from '@angular/platform-browser';
import { ApplicationConfig } from '@angular/core';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig } from '@handsontable/angular-wrapper';
import { mainTheme, registerTheme } from 'handsontable/themes';
import { AppComponent } from './app/app.component';

const theme = registerTheme(mainTheme).setColorScheme('auto');

export const appConfig: ApplicationConfig = {
  providers: [{
    provide: HOT_GLOBAL_CONFIG,
    useValue: { theme: theme } as HotGlobalConfig
  }],
};

bootstrapApplication(AppComponent, appConfig);

    This global configuration is then merged with local settings when initializing each Handsontable instance.

    Using HotGlobalConfigService

    You can manage the global theme at runtime using the HotGlobalConfigService.

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

const theme = registerTheme(horizonTheme).setColorScheme('dark');

hotConfigService.setConfig({ theme: theme });

    When the configuration changes, all Handsontable instances will automatically update their settings.

    Theme settings hierarchy

    When both a global theme and a local theme are defined, the local setting takes precedence. This means:

    • Local Setting: If a <hot-table> component is provided with a theme via its settings input, that value overrides the global default.
    • Global Setting: If no local theme is specified, the component falls back to the global configuration provided via the injection token or the configuration service.

    This hierarchy ensures that you can define a consistent default theme for your entire application while still allowing individual components to customize their appearance when needed.

    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: