Handsontable DataGrid with Tabler Icons
This tutorial shows you how to swap all of Handsontable DataGrid’s built-in icons for the Tabler Icons webfont. You register a theme, map each icon slot to a Tabler class list, and pass the theme to the grid as an object.
<script setup lang="ts">import { HotTable } from '@handsontable/vue3';import { registerAllModules } from 'handsontable/registry';import { mainTheme, registerTheme } from 'handsontable/themes';import type { GridSettings } from 'handsontable/settings';
// Register all Handsontable's modules.registerAllModules();
/* start:skip-in-preview */// In your project, install `@tabler/icons-webfont` and import its stylesheet instead.const tablerCss = document.createElement('link');
tablerCss.rel = 'stylesheet';tablerCss.href = 'https://cdn.jsdelivr.net/npm/@tabler/icons-webfont@3.31.0/dist/tabler-icons.min.css';document.head.appendChild(tablerCss);/* end:skip-in-preview */
// Every icon slot the grid renders, mapped to a Tabler Icons class list.const tablerTheme = registerTheme(mainTheme);
tablerTheme.params({ icons: { arrowRight: 'ti ti-chevron-right', arrowRightWithBar: 'ti ti-chevron-right-pipe', arrowLeft: 'ti ti-chevron-left', arrowLeftWithBar: 'ti ti-chevron-left-pipe', arrowDown: 'ti ti-chevron-down', menu: 'ti ti-menu-2', selectArrow: 'ti ti-caret-down-filled', arrowNarrowUp: 'ti ti-arrow-narrow-up', arrowNarrowDown: 'ti ti-arrow-narrow-down', check: 'ti ti-check', checkbox: 'ti ti-check', caretHiddenLeft: 'ti ti-caret-left-filled', caretHiddenRight: 'ti ti-caret-right-filled', caretHiddenUp: 'ti ti-caret-up-filled', caretHiddenDown: 'ti ti-caret-down-filled', collapseOff: 'ti ti-minus', collapseOn: 'ti ti-plus', radio: 'ti ti-point-filled', chipClose: 'ti ti-x', search: 'ti ti-search', plus: 'ti ti-plus', menuList: 'ti ti-list', },});
const hotSettings: GridSettings = { // The mapping applies only when the theme is passed as an object. theme: tablerTheme, data: [ { product: 'Standing desk', category: 'Furniture', inStock: true, units: 24 }, { product: 'Monitor arm', category: 'Accessories', inStock: true, units: 61 }, { product: 'Ergonomic chair', category: 'Furniture', inStock: false, units: 0 }, { product: 'USB-C dock', category: 'Electronics', inStock: true, units: 138 }, { product: 'Desk lamp', category: 'Lighting', inStock: true, units: 45 }, { product: 'Cable tray', category: 'Accessories', inStock: false, units: 0 }, ], columns: [ { data: 'product' }, { data: 'category', type: 'dropdown', source: ['Furniture', 'Accessories', 'Electronics', 'Lighting'] }, { data: 'inStock', type: 'checkbox' }, { data: 'units', type: 'numeric' }, ], colHeaders: ['Product', 'Category', 'In stock', 'Units'], rowHeaders: true, columnSorting: true, dropdownMenu: true, filters: true, // The hidden Units column puts a caret on the In stock header. hiddenColumns: { columns: [3], indicators: true }, height: 260, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/};</script>
<template> <div id="example1"> <HotTable :settings="hotSettings" /> </div></template>Overview
Every icon in the grid is an <i class="ht-icon ht-icon-<name>"> element painted from a CSS mask. The theme icons parameter lets you replace that mask with something else per icon slot. For an icon font, the value is a class list: Handsontable adds the classes to the element together with ht-icon--external, which turns off the built-in mask and sizes the font glyph to the theme’s icon size. The font’s own stylesheet then draws the glyph.
Tabler Icons ships a webfont whose classes follow the ti ti-<icon-name> pattern, so a mapping is one string per slot.
Difficulty: Beginner
Time: ~10 minutes
Stack: Handsontable, @tabler/icons-webfont
Prerequisites
- Handsontable 19.0 or later. Earlier versions draw icons as CSS pseudo-elements, which the
iconsparameter cannot replace. - A build that lets you pass the theme as an object through the
themeoption. See Requires a theme object below.
Install the Tabler webfont
Terminal window npm install @tabler/icons-webfontImport the stylesheet once, before the grid renders:
import '@tabler/icons-webfont/dist/tabler-icons.min.css';The live example above adds the same stylesheet from a CDN with a
<link>element, so it runs without a build step. In your project, prefer the npm import.Register a theme and map the icon slots
Start from a built-in theme and pass an
iconsobject toparams(). Each key is an icon slot, and each value is the Tabler class list for that slot:import { mainTheme, registerTheme } from 'handsontable/themes';const tablerTheme = registerTheme(mainTheme);tablerTheme.params({icons: {menu: 'ti ti-menu-2',selectArrow: 'ti ti-caret-down-filled',check: 'ti ti-check',// one entry per slot, see the table below},});Slots you leave out keep their built-in glyph, so you can migrate one icon at a time.
Pass the theme as an object
new Handsontable(container, {theme: tablerTheme,// other options});The theme must be an object
A class-list mapping runs in JavaScript when the grid builds each icon element. That only happens when the grid receives the theme through the
themeoption as a configuration object. Putting aht-theme-mainclass on the container element, or passing athemeNamestring, applies the theme through the stylesheet alone, and theiconsmapping does nothing. There is no warning.Check the icons in context
The example hides the Units column (
hiddenColumns: { columns: [3], indicators: true }), so the In stock header shows the hidden-column caret. Its box is a fixed 10px, smaller than the icon size every other slot uses, and the grid sizes a font glyph in it to match, so no extra CSS is needed. Sort a column, open a header menu, or open the Category dropdown to see the other slots.Tabler glyphs paint with
currentColor, so every state color the theme defines (hover, checked, disabled, active header) applies to them unchanged.
Icon slot reference
| Slot | Where it renders | Tabler class list |
|---|---|---|
arrowRight | Submenu arrow, pagination next | ti ti-chevron-right |
arrowRightWithBar | Pagination last page | ti ti-chevron-right-pipe |
arrowLeft | Pagination previous, sheets bar | ti ti-chevron-left |
arrowLeftWithBar | Pagination first page | ti ti-chevron-left-pipe |
arrowDown | Pagination page-size select | ti ti-chevron-down |
menu | Column header menu button | ti ti-menu-2 |
selectArrow | Autocomplete, dropdown, and select arrows, filters condition select, sheets bar tab menu | ti ti-caret-down-filled |
arrowNarrowUp | Ascending sort indicator | ti ti-arrow-narrow-up |
arrowNarrowDown | Descending sort indicator | ti ti-arrow-narrow-down |
check | Menu item check mark | ti ti-check |
checkbox | Checkbox cell tick, multi-select list tick | ti ti-check |
caretHiddenLeft | Hidden column, on the header before the gap | ti ti-caret-left-filled |
caretHiddenRight | Hidden column, on the header after the gap | ti ti-caret-right-filled |
caretHiddenUp | Hidden row, on the header above the gap | ti ti-caret-up-filled |
caretHiddenDown | Hidden row, on the header below the gap | ti ti-caret-down-filled |
collapseOff | Expanded group header, expanded nested row, mixed menu item | ti ti-minus |
collapseOn | Collapsed group header, collapsed nested row | ti ti-plus |
radio | Filters condition radio dot | ti ti-point-filled |
chipClose | Multi-select chip remove, notification close | ti ti-x |
search | Multi-select editor search | ti ti-search |
plus | Sheets bar add sheet | ti ti-plus |
menuList | Sheets bar all sheets | ti ti-list |
Pagination arrows, the submenu arrow, and the sheets bar arrows mirror in a right-to-left layout on their own, so the left and right slots take the physical left and right glyphs.
Limitations
- Runtime theme changes. A remapped icon reaches every slot without re-creating the grid, but not at the same moment: pagination, the sheets bar, and notifications update their icons in place at once, the header menu button on the next header render, the filters select and radio on the next menu open, and the select editor arrow on the next editor open.
- Class-based theming. As described in Step 3, a class on the container or a
themeNamestring ignores theiconsmapping. - Glyph metrics. Tabler glyphs are drawn on a 24px grid with a 2px stroke. At the default 16px icon size they read slightly lighter than the built-in set. Raise
--ht-icon-sizeor pick a heavier Tabler variant if that matters for your design.