Handsontable with shadcn/ui

Overview

This recipe shows how to integrate Handsontable into a Next.js that uses shadcn/ui by registering a custom theme that uses shadcn’s CSS variables for colors, Lucide-style icons, and Horizon tokens. The grid follows your design system.

Difficulty: Beginner
Time: ~15 minutes
Stack: Next.js, shadcn/ui (Tailwind CSS), Handsontable, @handsontable/react-wrapper

What You’ll Get

A Handsontable grid with a custom theme (registerTheme('shadcn-data-grid', { icons, colors, tokens })) where colors map to shadcn’s --primary, --background, --foreground, --muted, --border, etc. via var(--…).
Icons using Lucide-style SVGs (data URIs with currentColor) so they match your theme.
Tokens from Handsontable’s Horizon set, with overrides (e.g. wrapperBorderRadius) to match shadcn’s --radius.

Prerequisites

A Next.js project with shadcn/ui already set up (e.g. app/globals.css with shadcn imports and :root variables).
shadcn’s CSS variables defined (e.g. --primary, --background, --foreground, --muted, --border, --radius).
This recipe uses lib/ for theme and helpers and components/ for the grid, adjust paths if your structure differs.

Install Handsontable

In your project root:
Terminal window
```
1
pnpm add handsontable @handsontable/react-wrapper
```
(or npm install / yarn add). Use @handsontable/react-wrapper for HotTable + HotColumn and HotTableRef.

Register modules

1
import { registerAllModules } from 'handsontable/registry';
2
import { registerTheme } from 'handsontable/themes';
3

4
registerAllModules();

Define shadcn colors for the theme

Create a colors object that maps Handsontable’s expected shape to shadcn CSS variables. The grid will follow light/dark automatically because var(--…) is resolved at render time.

Option A – use the built-in shadcn colors:
You can import the official mapping from Handsontable instead of defining your own:

1
import colorsShadcn from 'handsontable/themes/static/variables/colors/shadcn';

Option B – define your own (e.g. to match your globals.css):
File: lib/theme/colorsShadcn.ts

1
/**
2
 * Handsontable theme colors mapped to shadcn CSS variables (globals.css).
3
 * Structure must match what tokens/main expects: palette (50–950), primary (100–600), white, black, transparent.
4
 * Uses var(--…) so the grid follows your shadcn theme and dark mode.
5
 */
6
export const colorsShadcn = {
7
  palette: {
8
    50: "var(--color-neutral-50)",
9
    100: "var(--color-neutral-200)",
10
    200: "var(--color-neutral-100)",
11
    300: "var(--color-neutral-300)",
12
    400: "var(--color-neutral-400)",
13
    500: "var(--color-neutral-500)",
14
    600: "var(--color-neutral-600)",
15
    700: "var(--color-neutral-700)",
16
    800: "var(--color-neutral-800)",
17
    900: "var(--color-neutral-900)",
18
    950: "var(--color-neutral-950)",
19
  },
20
  primary: {
21
    100: "var(--primary)",
22
    200: "var(--primary)",
23
    300: "var(--primary)",
24
    400: "var(--color-neutral-900)",
25
    500: "var(--primary)",
26
    600: "var(--color-neutral-800)",
27
  },
28
  white: "var(--background)",
29
  black: "var(--foreground)",
30
  transparent: "transparent",
31
}

Define Lucide-style icons for the theme

Handsontable themes accept an icons object. Use SVGs with currentColor so they follow your text/foreground color. Export as data URIs or inline SVG strings keyed by the theme’s expected icon keys.

File: lib/theme/iconsShadcn.ts

1
/**
2
 * Handsontable theme icons using Lucide (shadcn) icon set.
3
 * SVGs use currentColor so they follow shadcn theme. Keys must match VALID_ICON_KEYS.
4
 */
5
const lucideAttrs =
6
  'xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"';
7

8
function icon(svgContent: string): string {
9
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`<svg ${lucideAttrs}>${svgContent}</svg>`)}`;
10
}
11

12
// Lucide: ChevronRight, ChevronLeft, ChevronDown, ChevronUp, ChevronsRight, ChevronsLeft, Check, Menu, Plus, Minus, Circle (filled for radio)
13
export const iconsShadcn = {
14
  arrowRight: icon('<path d="m9 18 6-6-6-6"/>'),
15
  arrowRightWithBar: icon('<path d="m6 17 5-5-5-5"/><path d="m13 17 5-5-5-5"/>'),
16
  arrowLeft: icon('<path d="m15 18-6-6 6-6"/>'),
17
  arrowLeftWithBar: icon('<path d="m11 17-5-5 5-5"/><path d="m18 17-5-5 5-5"/>'),
18
  arrowDown: icon('<path d="m6 9 6 6 6-6"/>'),
19
  menu: icon('<path d="M4 5h16"/><path d="M4 12h16"/><path d="M4 19h16"/>'),
20
  selectArrow: icon('<path d="m6 9 6 6 6-6"/>'),
21
  arrowNarrowUp: icon('<path d="m18 15-6-6-6 6"/>'),
22
  arrowNarrowDown: icon('<path d="m6 9 6 6 6-6"/>'),
23
  check: icon('<g transform="translate(3,3) scale(0.75)"><path d="M20 6 9 17l-5-5"/></g>'),
24
  checkbox: icon('<g transform="translate(3,3) scale(0.75)"><path d="M20 6 9 17l-5-5"/></g>'),
25
  caretHiddenLeft: icon('<path d="m15 18-6-6 6-6"/>'),
26
  caretHiddenRight: icon('<path d="m9 18 6-6-6-6"/>'),
27
  caretHiddenUp: icon('<path d="m18 15-6-6-6 6"/>'),
28
  caretHiddenDown: icon('<path d="m6 9 6 6 6-6"/>'),
29
  collapseOff: icon('<path d="M5 12h14"/>'),
30
  collapseOn: icon('<path d="M5 12h14"/><path d="M12 5v14"/>'),
31
  radio: icon('<circle cx="12" cy="12" r="6" fill="currentColor"/>'),
32
} as const;

Use the exact icon keys required by your Handsontable theme (e.g. from the theme’s type or docs).

Register the custom theme and create the grid component

Import Horizon tokens (or another built-in token set), override tokens to match shadcn (e.g. --radius), and register the theme. Then use HotTable + HotColumn with that theme.

Helpers (data and config): Create a module that exports sample grid data and shared HotTable options. The data array should have one object per row, with keys matching your column data props (name, age, country, city, isActive, interest, etc.). The config object holds common props like licenseKey and height.

File: lib/helpers.ts

1
import { HotTableProps } from "@handsontable/react-wrapper";
2

3
export const config: Partial<HotTableProps> = {
4
  width: "100%",
5
  height: "auto",
6
  licenseKey: "non-commercial-and-evaluation",
7
  autoWrapRow: true,
8
  filters: true,
9
  // Add more options: nestedHeaders, contextMenu, dropdownMenu, pagination, etc.
10
};
11

12
export const data = [
13
  { name: "Alice", age: 28, country: "USA", city: "New York", isActive: true, interest: "Tech Gadgets", favoriteProduct: "Laptop", lastLoginDate: "Jan 15, 2025", lastLoginTime: "09:30" },
14
  { name: "Bob", age: 34, country: "UK", city: "London", isActive: false, interest: "Books & Literature", favoriteProduct: "Headphones", lastLoginDate: "Feb 01, 2025", lastLoginTime: "14:00" },
15
  // Add more rows; keys must match HotColumn data props
16
];

Then in your grid component (File: components/DataGrid.tsx):

1
"use client";
2
import { forwardRef } from "react";
3
import { HotTable, HotColumn, HotTableRef } from "@handsontable/react-wrapper";
4
import { registerTheme } from "handsontable/themes";
5
import { registerAllModules } from "handsontable/registry";
6

7
import tokensHorizon from 'handsontable/themes/static/variables/tokens/horizon';
8

9
import { colorsShadcn } from "/theme/colorsShadcn";
10
import { iconsShadcn } from "/theme/iconsShadcn";
11
import { data, config } from "/helpers";
12

13
registerAllModules();
14

15
const shadcnDataGridTheme = registerTheme('shadcn-data-grid', {
16
  icons: iconsShadcn,
17
  colors: colorsShadcn,
18
  tokens: tokensHorizon,
19
}).params({
20
  tokens: {
21
    wrapperBorderRadius: "var(--radius)",
22
  },
23
})
24

25
const DataGrid = forwardRef<HotTableRef, unknown>(function DataGrid(_, ref) {
26
  return (<HotTable
27
    ref={ref}
28
    theme={shadcnDataGridTheme}
29
    data={data}
30
    {...config}
31
  >
32
    <HotColumn data="name" width={160} />
33
    <HotColumn data="age" type="numeric" width={100} />
34
    <HotColumn
35
      data="country"
36
      type="autocomplete"
37
      source={[
38
        "Germany",
39
        "China",
40
        "France",
41
        "Netherlands",
42
        "Switzerland",
43
        "USA",
44
        "Canada",
45
        "UK",
46
        "Australia",
47
        "Spain",
48
        "Japan",
49
        "Brazil",
50
        "South Korea",
51
        "Mexico",
52
      ]}
53
      strict={true}
54
      allowInvalid={true}
55
      width={160}
56
    />
57
    <HotColumn
58
      data="city"
59
      type="dropdown"
60
      source={[
61
        "Walldorf",
62
        "Shenzhen",
63
        "Lyon",
64
        "Amsterdam",
65
        "Zurich",
66
        "New York",
67
        "Toronto",
68
        "London",
69
        "Sydney",
70
        "Los Angeles",
71
        "Barcelona",
72
        "Tokyo",
73
        "Manchester",
74
        "Sao Paulo",
75
        "Miami",
76
        "Madrid",
77
        "Seoul",
78
        "Vancouver",
79
        "Valencia",
80
        "Chicago",
81
        "Mexico City",
82
        "Houston",
83
      ]}
84
      width={160}
85
    />
86
    <HotColumn
87
      data="isActive"
88
      type="checkbox"
89
      className="htCenter"
90
      width={120}
91
    />
92
    <HotColumn
93
      data="interest"
94
      type="dropdown"
95
      source={[
96
        "Electronics",
97
        "Fashion",
98
        "Tech Gadgets",
99
        "Home Decor",
100
        "Sports & Fitness",
101
        "Books & Literature",
102
        "Beauty & Personal Care",
103
        "Food & Cooking",
104
        "Travel & Adventure",
105
        "Art & Collectibles",
106
      ]}
107
      width={220}
108
    />
109
    <HotColumn data="favoriteProduct" width={220} />
110
    <HotColumn
111
      data="lastLoginDate"
112
      type="date"
113
      className="htRight"
114
      correctFormat={true}
115
      dateFormat="MMM DD, YYYY"
116
      width={180}
117
    />
118
    <HotColumn
119
      data="lastLoginTime"
120
      type="time"
121
      className="htRight"
122
      correctFormat={true}
123
      timeFormat="HH:mm"
124
      width={180}
125
    />
126
  </HotTable>);
127
});

Use the grid in your page (e.g. app/page.tsx): import DataGrid from "/DataGrid" and render <DataGrid />. The full example exports a DataGridWrapper that wires the grid ref to URL search params for filtering (see Complete example below).

Complete example (minimal single-file shape)

1
"use client";
2
import { useRef, useEffect, memo, forwardRef } from "react";
3
import { useSearchParams } from "next/navigation";
4
import { HotTable, HotColumn, HotTableRef } from "@handsontable/react-wrapper";
5
import { registerTheme } from "handsontable/themes";
6
import { registerAllModules } from "handsontable/registry";
7

8
import tokensHorizon from 'handsontable/themes/static/variables/tokens/horizon';
9

10
import { colorsShadcn } from "/theme/colorsShadcn";
11
import { iconsShadcn } from "/theme/iconsShadcn";
12
import { data, config } from "/helpers";
13

14
registerAllModules();
15

16
const shadcnDataGridTheme = registerTheme('shadcn-data-grid', {
17
  icons: iconsShadcn,
18
  colors: colorsShadcn,
19
  tokens: tokensHorizon,
20
}).params({
21
  tokens: {
22
    wrapperBorderRadius: "var(--radius)",
23
  },
24
})
25

26
const DataGrid = forwardRef<HotTableRef, unknown>(function DataGrid(_, ref) {
27
  return (<HotTable
28
    ref={ref}
29
    theme={shadcnDataGridTheme}
30
    data={data}
31
    {...config}
32
  >
33
    <HotColumn data="name" width={160} />
34
    <HotColumn data="age" type="numeric" width={100} />
35
    <HotColumn
36
      data="country"
37
      type="autocomplete"
38
      source={[
39
        "Germany",
40
        "China",
41
        "France",
42
        "Netherlands",
43
        "Switzerland",
44
        "USA",
45
        "Canada",
46
        "UK",
47
        "Australia",
48
        "Spain",
49
        "Japan",
50
        "Brazil",
51
        "South Korea",
52
        "Mexico",
53
      ]}
54
      strict={true}
55
      allowInvalid={true}
56
      width={160}
57
    />
58
    <HotColumn
59
      data="city"
60
      type="dropdown"
61
      source={[
62
        "Walldorf",
63
        "Shenzhen",
64
        "Lyon",
65
        "Amsterdam",
66
        "Zurich",
67
        "New York",
68
        "Toronto",
69
        "London",
70
        "Sydney",
71
        "Los Angeles",
72
        "Barcelona",
73
        "Tokyo",
74
        "Manchester",
75
        "Sao Paulo",
76
        "Miami",
77
        "Madrid",
78
        "Seoul",
79
        "Vancouver",
80
        "Valencia",
81
        "Chicago",
82
        "Mexico City",
83
        "Houston",
84
      ]}
85
      width={160}
86
    />
87
    <HotColumn
88
      data="isActive"
89
      type="checkbox"
90
      className="htCenter"
91
      width={120}
92
    />
93
    <HotColumn
94
      data="interest"
95
      type="dropdown"
96
      source={[
97
        "Electronics",
98
        "Fashion",
99
        "Tech Gadgets",
100
        "Home Decor",
101
        "Sports & Fitness",
102
        "Books & Literature",
103
        "Beauty & Personal Care",
104
        "Food & Cooking",
105
        "Travel & Adventure",
106
        "Art & Collectibles",
107
      ]}
108
      width={220}
109
    />
110
    <HotColumn data="favoriteProduct" width={220} />
111
    <HotColumn
112
      data="lastLoginDate"
113
      type="date"
114
      className="htRight"
115
      correctFormat={true}
116
      dateFormat="MMM DD, YYYY"
117
      width={180}
118
    />
119
    <HotColumn
120
      data="lastLoginTime"
121
      type="time"
122
      className="htRight"
123
      correctFormat={true}
124
      timeFormat="HH:mm"
125
      width={180}
126
    />
127
  </HotTable>);
128
});
129

130
const MemoizedDataGrid = memo(DataGrid);
131

132
function DataGridWrapper() {
133
  const hotTableRef = useRef<HotTableRef>(null);
134
  const searchParams = useSearchParams();
135

136
  useEffect(() => {
137
    const hot = hotTableRef.current?.hotInstance;
138
    const params = Object.fromEntries(searchParams.entries());
139

140
    if (hot) {
141
      const filtersPlugin = hot.getPlugin('filters');
142

143
      if (filtersPlugin) {
144
        filtersPlugin.clearConditions();
145

146
        if (params.q) filtersPlugin.addCondition(0, 'begins_with', [params.q]); // Name
147
        if (params.country) filtersPlugin.addCondition(2, 'contains', [params.country]); // Country
148
        if (params.status) filtersPlugin.addCondition(4, 'eq', [params.status === 'active']); // Active (checkbox)
149

150
        filtersPlugin.filter();
151
        hot?.render();
152
      }
153
    }
154
  }, [searchParams]);
155

156
  return (
157
    <MemoizedDataGrid ref={hotTableRef} />
158
  );
159
}
160

161
export default DataGridWrapper;

Congratulations! You’ve integrated Handsontable with your shadcn/ui design system using a custom theme, CSS variables, and a filterable data grid that matches your app’s look and feel!

Themes – Built-in themes and Theme API
Theme customization – Theme API parameters and CSS variable reference
Design system (Figma) – Figma kit and design tokens