Conditional row coloring

In this tutorial, you will color entire rows based on a status column value. You will learn how to use the cells callback and className to apply conditional CSS classes that update automatically after every edit.

1
import Handsontable from "handsontable/base";
2
import { registerAllModules } from "handsontable/registry";
3
registerAllModules();
4
const STATUS_ROW_CLASSES = {
5
    active: "ht-demo-row-status-active",
6
    pending: "ht-demo-row-status-pending",
7
    inactive: "ht-demo-row-status-inactive",
8
};
9
function statusToRowClass(status) {
10
    if (typeof status !== "string") {
11
        return undefined;
12
    }
13
    return STATUS_ROW_CLASSES[status];
14
}
15
/* start:skip-in-preview */
16
const data = [
17
    { task: "Invoice export", owner: "A. Lee", status: "active" },
18
    { task: "SSO rollout", owner: "M. Costa", status: "pending" },
19
    { task: "Legacy reports", owner: "J. Park", status: "inactive" },
20
    { task: "API docs", owner: "R. Singh", status: "active" },
21
    { task: "Mobile parity", owner: "T. Nguyen", status: "pending" },
22
];
23
/* end:skip-in-preview */
24
const container = document.querySelector("#example1");
25
const hotOptions = {
26
    data,
27
    licenseKey: "non-commercial-and-evaluation",
28
    rowHeaders: true,
29
    colHeaders: ["Task", "Owner", "Status"],
30
    height: "auto",
31
    width: "100%",
32
    columns: [
33
        { data: "task", type: "text", width: 220 },
34
        { data: "owner", type: "text", width: 120 },
35
        {
36
            data: "status",
37
            type: "dropdown",
38
            width: 120,
39
            source: ["active", "pending", "inactive"],
40
            strict: true,
41
            allowInvalid: false,
42
        },
43
    ],
44
    cells(row, _column, _prop) {
45
        const hot = this.instance;
46
        const visualRow = hot.toVisualRow(row);
47
        if (visualRow === null || visualRow < 0) {
48
            return {};
49
        }
50
        const status = hot.getDataAtRowProp(visualRow, "status");
51
        const rowClass = statusToRowClass(status);
52
        if (!rowClass) {
53
            return {};
54
        }
55
        return { className: rowClass };
56
    },
57
    afterValidate(isValid, _value, row, prop) {
58
        if (isValid) {
59
            return;
60
        }
61
        const col = this.propToCol(prop);
62
        const td = this.getCell(row, col);
63
        if (!td) {
64
            return;
65
        }
66
        td.classList.add("ht-demo-invalid-flash");
67
        setTimeout(() => td.classList.remove("ht-demo-invalid-flash"), 800);
68
    },
69
};
70
// eslint-disable-next-line no-unused-vars
71
const hot = new Handsontable(container, hotOptions);

1
import Handsontable from "handsontable/base";
2
import { registerAllModules } from "handsontable/registry";
3
import type { CellMeta, CellProperties } from "handsontable/settings";
4

5
registerAllModules();
6

7
const STATUS_ROW_CLASSES: Record<string, string> = {
8
  active: "ht-demo-row-status-active",
9
  pending: "ht-demo-row-status-pending",
10
  inactive: "ht-demo-row-status-inactive",
11
};
12

13
function statusToRowClass(status: unknown): string | undefined {
14
  if (typeof status !== "string") {
15
    return undefined;
16
  }
17

18
  return STATUS_ROW_CLASSES[status];
19
}
20

21
/* start:skip-in-preview */
22
const data = [
23
  { task: "Invoice export", owner: "A. Lee", status: "active" },
24
  { task: "SSO rollout", owner: "M. Costa", status: "pending" },
25
  { task: "Legacy reports", owner: "J. Park", status: "inactive" },
26
  { task: "API docs", owner: "R. Singh", status: "active" },
27
  { task: "Mobile parity", owner: "T. Nguyen", status: "pending" },
28
];
29
/* end:skip-in-preview */
30

31
const container = document.querySelector("#example1")!;
32

33
const hotOptions: Handsontable.GridSettings = {
34
  data,
35
  licenseKey: "non-commercial-and-evaluation",
36
  rowHeaders: true,
37
  colHeaders: ["Task", "Owner", "Status"],
38
  height: "auto",
39
  width: "100%",
40
  columns: [
41
    { data: "task", type: "text", width: 220 },
42
    { data: "owner", type: "text", width: 120 },
43
    {
44
      data: "status",
45
      type: "dropdown",
46
      width: 120,
47
      source: ["active", "pending", "inactive"],
48
      strict: true,
49
      allowInvalid: false,
50
    },
51
  ],
52
  cells(
53
    this: CellProperties,
54
    row: number,
55
    _column: number,
56
    _prop: string | number,
57
  ): CellMeta {
58
    const hot = this.instance;
59
    const visualRow = hot.toVisualRow(row);
60

61
    if (visualRow === null || visualRow < 0) {
62
      return {};
63
    }
64

65
    const status = hot.getDataAtRowProp(visualRow, "status");
66
    const rowClass = statusToRowClass(status);
67

68
    if (!rowClass) {
69
      return {};
70
    }
71

72
    return { className: rowClass };
73
  },
74
  afterValidate(
75
    this: Handsontable,
76
    isValid: boolean,
77
    _value: Handsontable.CellValue,
78
    row: number,
79
    prop: string | number,
80
  ): void {
81
    if (isValid) {
82
      return;
83
    }
84

85
    const col = this.propToCol(prop);
86
    const td = this.getCell(row, col);
87

88
    if (!td) {
89
      return;
90
    }
91

92
    td.classList.add("ht-demo-invalid-flash");
93
    setTimeout(() => td.classList.remove("ht-demo-invalid-flash"), 800);
94
  },
95
};
96

97
// eslint-disable-next-line no-unused-vars
98
const hot = new Handsontable(container, hotOptions);

1
/* Scoped to the recipe preview container */
2
#example1 td.ht-demo-row-status-active {
3
  background-color: rgba(26, 66, 232, 0.12);
4
  background-color: color-mix(in srgb, var(--ht-accent-color, #1a42e8) 12%, var(--ht-background-color, #ffffff));
5
}
6

7
#example1 td.ht-demo-row-status-pending {
8
  background-color: rgba(202, 138, 4, 0.14);
9
  background-color: color-mix(in srgb, var(--ht-warn-color, #ca8a04) 14%, var(--ht-background-color, #ffffff));
10
}
11

12
#example1 td.ht-demo-row-status-inactive {
13
  background-color: var(--ht-background-secondary-color, #f3f4f6);
14
  color: var(--ht-foreground-secondary-color, #6b7280);
15
}
16

17
/* Flash feedback for rejected edits (allowInvalid: false) */
18
#example1 td.ht-demo-invalid-flash {
19
  background-color: var(--ht-cell-error-background-color, rgba(250, 77, 50, 0.2)) !important;
20
  color: inherit;
21
}

Overview

This recipe shows how to tint every cell in a row based on a Status value (active, pending, or inactive). You map each status to a CSS class, attach that class to cells through Handsontable metadata, and keep colors correct on first load and after the user edits Status.

Difficulty: Beginner
Time: ~10 minutes
Libraries: None beyond Handsontable.

What You’ll Build

A grid that:

Tints active rows with a blue background
Tints pending rows with an amber background
Grays out inactive rows with muted text
Updates row colors instantly when the user changes the Status dropdown

Define the status-to-class mapping

Create a lookup object that maps each status string to a CSS class name. Keeping it in one place means you only touch one object if you add or rename statuses.
```
1
const STATUS_ROW_CLASSES: Record<string, string> = {
2
  active: 'ht-demo-row-status-active',
3
  pending: 'ht-demo-row-status-pending',
4
  inactive: 'ht-demo-row-status-inactive',
5
};
6

7
function statusToRowClass(status: unknown): string | undefined {
8
  if (typeof status !== 'string') {
9
    return undefined;
10
  }
11
  return STATUS_ROW_CLASSES[status];
12
}
```
Why a lookup object?
- All status-to-class rules live in one place.
- Adding a new status (archived, draft, …) requires one new entry — no scattered if/else chains.
- The helper function guards against non-string values (empty cells, null, numbers) and returns undefined so callers can skip the class safely.
Why prefix class names with ht-demo-?
- Avoids collisions with Handsontable’s own internal CSS classes.
- Makes it obvious in DevTools which classes come from your code.
Wire up the cells callback

The cells callback runs while Handsontable builds cell metadata before each render. Return a { className } object and Handsontable applies that class directly to the <td> element.
```
1
cells(
2
  this: CellProperties,
3
  row: number,
4
  _column: number,
5
  _prop: string | number,
6
): CellMeta {
7
  const hot = this.instance;
8
  const visualRow = hot.toVisualRow(row);
9

10
  if (visualRow === null || visualRow < 0) {
11
    return {};
12
  }
13

14
  const status = hot.getDataAtRowProp(visualRow, 'status');
15
  const rowClass = statusToRowClass(status);
16

17
  if (!rowClass) {
18
    return {};
19
  }
20

21
  return { className: rowClass };
22
},
```
Key points:
- cells receives the physical row index. You must call hot.toVisualRow(row) to get the visual index before reading data. Without this, sorting or row moves would read data from the wrong row.
- hot.getDataAtRowProp(visualRow, 'status') reads the Status value by property name, which works with object-based data ([{ task, owner, status }]).
- Returning {} (no class) for unrecognized statuses leaves the cell unstyled rather than applying a stale class.
- Use a regular function (not an arrow function) so this refers to the CellProperties object and this.instance gives you the grid.
Why cells and not a custom renderer?

The cells callback applies metadata to every column in the row automatically. A custom renderer would require you to add the same logic to each column’s renderer, or wrap the default renderer yourself. Use cells for row-level styling; use a renderer only when you need to change what is inside the cell.

Configure columns and data

Set up the grid with a dropdown for the Status column so the user can change values:

1
const hotOptions: Handsontable.GridSettings = {
2
  data,
3
  licenseKey: 'non-commercial-and-evaluation',
4
  rowHeaders: true,
5
  colHeaders: ['Task', 'Owner', 'Status'],
6
  height: 'auto',
7
  width: '100%',
8
  columns: [
9
    { data: 'task', type: 'text', width: 220 },
10
    { data: 'owner', type: 'text', width: 120 },
11
    {
12
      data: 'status',
13
      type: 'dropdown',
14
      width: 120,
15
      source: ['active', 'pending', 'inactive'],
16
      strict: true,
17
      allowInvalid: false,
18
    },
19
  ],
20
  cells(row, _column, _prop) { /* Step 2 */ },
21
};
22

23
const hot = new Handsontable(container, hotOptions);

Why strict: true and allowInvalid: false?

strict: true rejects any value that is not in the source list.
allowInvalid: false rolls back the edit instead of saving the invalid value.
Together they guarantee the Status column always holds a known value, so the class mapping always finds a match.

Handsontable runs a full render after every data change (including dropdown edits), which re-runs the cells callback automatically. Row colors stay in sync without any extra hooks or manual re-renders.

Write scoped CSS for each status

The cells callback places the class on each <td> element. Target td.ht-demo-row-status-* and scope every rule under your container ID (#example1) to prevent styles leaking to other tables on the page.
```
1
/* Blue tint for active rows */
2
#example1 td.ht-demo-row-status-active {
3
  background-color: color-mix(
4
    in srgb,
5
    var(--ht-accent-color, #1a42e8) 12%,
6
    var(--ht-background-color, #ffffff)
7
  );
8
}
9

10
/* Amber tint for pending rows */
11
#example1 td.ht-demo-row-status-pending {
12
  background-color: color-mix(
13
    in srgb,
14
    var(--ht-warn-color, #ca8a04) 14%,
15
    var(--ht-background-color, #ffffff)
16
  );
17
}
18

19
/* Gray background and muted text for inactive rows */
20
#example1 td.ht-demo-row-status-inactive {
21
  background-color: var(--ht-background-secondary-color, #f3f4f6);
22
  color: var(--ht-foreground-secondary-color, #6b7280);
23
}
```
Why td.ht-demo-row-status-* and not .ht-demo-row-status-* td?

Handsontable applies the className you return from cells directly to the <td> element itself. The selector must therefore read as “a <td> that has this class”, not “a <td> that is a child of something with this class”.

Why CSS custom properties (var(--ht-...)) with fallbacks?
- Theme tokens (--ht-accent-color, --ht-warn-color, etc.) automatically adapt to light, dark, and custom Handsontable themes.
- The fallback values (#1a42e8, #ca8a04, …) ensure colors work in environments that do not load a Handsontable theme.
Why color-mix()?
- color-mix(in srgb, <color> 12%, <background>) blends the accent color lightly into the background, creating a gentle tint rather than a solid block of color.
- The percentage controls intensity: lower means a subtler tint.
Flash feedback for rejected edits

With allowInvalid: false, Handsontable cancels the change and immediately resets valid back to true within the same microtask - before any render can happen. This means Handsontable’s built-in .htInvalid red background never appears: by the time the re-render runs, the cell is already valid again.

To give the user some feedback that their edit was rejected, use the afterValidate hook. It fires right after validation, while isValid is still false, giving you a brief window to add a temporary CSS class directly to the <td>:
```
1
afterValidate(isValid, _value, row, prop) {
2
  if (isValid) {
3
    return;
4
  }
5

6
  const col = this.propToCol(prop);
7
  const td = this.getCell(row, col);
8

9
  if (!td) {
10
    return;
11
  }
12

13
  td.classList.add('ht-demo-invalid-flash');
14
  setTimeout(() => td.classList.remove('ht-demo-invalid-flash'), 800);
15
},
```
Key points:
- this is the Handsontable instance inside any hook defined in the settings object (use a regular function, not an arrow function).
- this.propToCol(prop) converts the property name ('status') to a visual column index.
- this.getCell(row, col) returns the live <td> element at the visual row and column. It returns null if the row is outside the rendered viewport, so always guard with if (!td).
- The class is added directly to the DOM - no re-render is needed.
- The setTimeout removes the class after 800 ms, returning the cell to its normal status color.
Why not use .htInvalid directly?

The baseRenderer adds .htInvalid only when cellProperties.valid === false at render time. With allowInvalid: false, Handsontable sets valid back to true before the render. The hook fires before that reset, so it is the only reliable place to catch the isValid === false signal.

Add a matching CSS rule with !important so it overrides the status tint and color is preserved:
```
1
#example1 td.ht-demo-invalid-flash {
2
  background-color: var(--ht-cell-error-background-color, rgba(250, 77, 50, 0.2)) !important;
3
  color: inherit;
4
}
```
--ht-cell-error-background-color matches the same token used by .htInvalid, so the flash color is consistent with the theme.

How It Works - Complete Flow

Initial load: Handsontable calls cells for every cell. The callback reads the Status value and returns a class. Each <td> gets the matching CSS class applied to it.
CSS renders colors: The scoped CSS rules tint each <td> according to its class.
User selects a new status: The dropdown editor commits the value to the data source.
Handsontable re-renders: The cells callback runs again. The new class replaces the old one on every cell in that row.
Colors update instantly: No extra hooks, no manual re-renders needed.
User pastes or types an invalid value: afterValidate fires with isValid === false. The hook adds .ht-demo-invalid-flash directly to the <td>. After 800 ms the class is removed and the status color returns. The invalid value is never committed.

`cells` callback vs custom renderer

Approach	Pros	Trade-offs
`cells` + `className`	Styling lives in CSS. Works with all built-in cell types and editors. One callback covers all columns in the row.	You rely on Handsontable to merge `className` into the DOM.
Custom `renderer`	Full control of `innerHTML`, extra markup, and per-cell logic.	Row-wide styling requires duplicating logic across columns or wrapping the default renderer.

You can combine both: use cells for row-level classes and a custom renderer only where cell content needs special HTML.

What you learned

How to use the cells callback to return a className for every cell in a row based on a status column value.
Why scoped CSS classes work better than inline styles for row coloring — they stay consistent with Handsontable themes and update automatically on re-render.
How Handsontable calls cells again after every edit, so no extra hooks are needed to keep row colors accurate after the user changes a status.
How to add a temporary flash class in afterValidate to signal an invalid value without interrupting the color logic.

Next steps

Explore frozen summary row to pin a styled totals row at the bottom while keeping the data rows color-coded.
Explore sparkline cell renderer for a more advanced renderer that draws SVG charts inside individual cells.

Conditional row coloring

Overview

What You’ll Build

Define the status-to-class mapping

Wire up the cells callback

Configure columns and data

Write scoped CSS for each status

Flash feedback for rejected edits

How It Works - Complete Flow

cells callback vs custom renderer

What you learned

Next steps

Related

Wire up the `cells` callback

`cells` callback vs custom renderer