Conditional formatting

Style cells dynamically based on their values, so you can highlight outliers, flag errors, or visualize data ranges.

Overview

Conditional formatting changes a cell’s appearance based on the data it holds. As values change, the formatting updates on the next render.

Choose an approach based on your goal:

Use className with the cells callback when you want reusable CSS classes driven by cell values. This is the recommended default.
Use the renderer option when you need inline styles or want to transform the displayed value.
Combine a renderer with a computed background color when you want a color scale that reflects each value’s magnitude.

For static styling that does not depend on cell values, see Formatting cells.

Prerequisites

A Handsontable instance with data loaded.
A stylesheet, if you format cells through custom CSS classes.
Familiarity with the cascading configuration model, where cell settings override column settings, which override global settings. See Configuration options.

Highlight cells by value with a CSS class

Return a className from the cells callback to style cells by value. The callback runs for every cell, so you can inspect the value and assign a class conditionally.

This example uses the cascading model on two levels: the Company column sets a static className through its columns entry, while the cells callback adds a loss class to negative quarters and a strong-quarter class to quarters above 10. The loss class pairs its red color with a leading marker, so the value stays readable without color.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
// register Handsontable's modules
4
registerAllModules();
5
const data = [
6
    ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
7
    ['Vertex Industries', 12.5, 11.9, 13.2, 14],
8
    ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
9
    ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
10
    ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
11
    ['Meridian Retail', 6, 7.3, 8.1, 9.4],
12
];
13
const ExampleComponent = () => {
14
    return (<HotTable data={data} colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']} licenseKey="non-commercial-and-evaluation" height="auto" columns={[
15
            { className: 'company-name' },
16
            { type: 'numeric' },
17
            { type: 'numeric' },
18
            { type: 'numeric' },
19
            { type: 'numeric' },
20
        ]} cells={function (row, col) {
21
            const cellProperties = {};
22
            if (col > 0) {
23
                cellProperties.className = '';
24
                const value = data[row]?.[col];
25
                if (typeof value === 'number' && value < 0) {
26
                    cellProperties.className = 'loss';
27
                }
28
                else if (typeof value === 'number' && value > 10) {
29
                    cellProperties.className = 'strong-quarter';
30
                }
31
            }
32
            return cellProperties;
33
        }}/>);
34
};
35
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import Handsontable from 'handsontable/base';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const data = [
9
  ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
10
  ['Vertex Industries', 12.5, 11.9, 13.2, 14],
11
  ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
12
  ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
13
  ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
14
  ['Meridian Retail', 6, 7.3, 8.1, 9.4],
15
];
16

17
const ExampleComponent = () => {
18
  return (
19
    <HotTable
20
      data={data}
21
      colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']}
22
      licenseKey="non-commercial-and-evaluation"
23
      height="auto"
24
      columns={[
25
        { className: 'company-name' },
26
        { type: 'numeric' },
27
        { type: 'numeric' },
28
        { type: 'numeric' },
29
        { type: 'numeric' },
30
      ]}
31
      cells={function (row, col) {
32
        const cellProperties: Handsontable.CellMeta = {};
33

34
        if (col > 0) {
35
          cellProperties.className = '';
36

37
          const value = data[row]?.[col];
38

39
          if (typeof value === 'number' && value < 0) {
40
            cellProperties.className = 'loss';
41
          } else if (typeof value === 'number' && value > 10) {
42
            cellProperties.className = 'strong-quarter';
43
          }
44
        }
45

46
        return cellProperties;
47
      }}
48
    />
49
  );
50
};
51

52
export default ExampleComponent;

1
#example1 .handsontable td.company-name {
2
  font-weight: 600;
3
}
4

5
#example1 .handsontable td.loss {
6
  color: #d81e2c;
7
  background: var(--ht-cell-error-background-color, rgba(216, 30, 44, 0.14));
8
  background: color-mix(in srgb, #d81e2c 16%, var(--ht-background-color, #ffffff));
9
}
10

11
#example1 .handsontable td.loss::before {
12
  content: "▼ ";
13
}
14

15
#example1 .handsontable td.strong-quarter {
16
  color: #157a3d;
17
  font-weight: 600;
18
}
19

20
html[data-theme="dark"] #example1 .handsontable td.loss {
21
  color: #ff5c70;
22
  background: color-mix(in srgb, #ff5c70 22%, var(--ht-background-color, #000000));
23
}
24

25
html[data-theme="dark"] #example1 .handsontable td.strong-quarter {
26
  color: #22c55e;
27
}

Format cells with a custom renderer

Use a renderer when a CSS class is not enough - for example, when you need to transform the displayed value or apply inline styles computed at render time.

This renderer formats each quarter as a currency amount and shows losses in an accounting format, ($1.3M). The parentheses convey a loss on their own, so the red color is a secondary signal.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { registerRenderer } from 'handsontable/renderers';
4
import { textRenderer } from 'handsontable/renderers/textRenderer';
5
// register Handsontable's modules
6
registerAllModules();
7
const data = [
8
    ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
9
    ['Vertex Industries', 12.5, 11.9, 13.2, 14],
10
    ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
11
    ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
12
    ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
13
    ['Meridian Retail', 6, 7.3, 8.1, 9.4],
14
];
15
// display losses in an accounting format, so color is not the only signal
16
const profitRenderer = (instance, td, row, col, prop, value, cellProperties) => {
17
    const amount = Number(value);
18
    td.classList.remove('loss-cell');
19
    if (!Number.isFinite(amount)) {
20
        textRenderer(instance, td, row, col, prop, value, cellProperties);
21
        return;
22
    }
23
    const formatted = amount < 0
24
        ? `($${Math.abs(amount).toFixed(1)}M)`
25
        : `$${amount.toFixed(1)}M`;
26
    textRenderer(instance, td, row, col, prop, formatted, cellProperties);
27
    if (amount < 0) {
28
        td.classList.add('loss-cell');
29
    }
30
};
31
registerRenderer('profitRenderer', profitRenderer);
32
const ExampleComponent = () => {
33
    return (<HotTable data={data} colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']} licenseKey="non-commercial-and-evaluation" height="auto" columns={[
34
            {},
35
            { renderer: 'profitRenderer' },
36
            { renderer: 'profitRenderer' },
37
            { renderer: 'profitRenderer' },
38
            { renderer: 'profitRenderer' },
39
        ]}/>);
40
};
41
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { BaseRenderer, registerRenderer } from 'handsontable/renderers';
4
import { textRenderer } from 'handsontable/renderers/textRenderer';
5

6
// register Handsontable's modules
7
registerAllModules();
8

9
const data = [
10
  ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
11
  ['Vertex Industries', 12.5, 11.9, 13.2, 14],
12
  ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
13
  ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
14
  ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
15
  ['Meridian Retail', 6, 7.3, 8.1, 9.4],
16
];
17

18
// display losses in an accounting format, so color is not the only signal
19
const profitRenderer: BaseRenderer = (instance, td, row, col, prop, value, cellProperties) => {
20
  const amount = Number(value);
21

22
  td.classList.remove('loss-cell');
23

24
  if (!Number.isFinite(amount)) {
25
    textRenderer(instance, td, row, col, prop, value, cellProperties);
26

27
    return;
28
  }
29

30
  const formatted = amount < 0
31
    ? `($${Math.abs(amount).toFixed(1)}M)`
32
    : `$${amount.toFixed(1)}M`;
33

34
  textRenderer(instance, td, row, col, prop, formatted, cellProperties);
35

36
  if (amount < 0) {
37
    td.classList.add('loss-cell');
38
  }
39
};
40

41
registerRenderer('profitRenderer', profitRenderer);
42

43
const ExampleComponent = () => {
44
  return (
45
    <HotTable
46
      data={data}
47
      colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']}
48
      licenseKey="non-commercial-and-evaluation"
49
      height="auto"
50
      columns={[
51
        {},
52
        { renderer: 'profitRenderer' },
53
        { renderer: 'profitRenderer' },
54
        { renderer: 'profitRenderer' },
55
        { renderer: 'profitRenderer' },
56
      ]}
57
    />
58
  );
59
};
60

61
export default ExampleComponent;

1
#example2 .handsontable td.loss-cell {
2
  color: #d81e2c;
3
  font-weight: 600;
4
}
5

6
html[data-theme="dark"] #example2 .handsontable td.loss-cell {
7
  color: #ff5c70;
8
}

Build a color scale

To visualize magnitude, compute a background color from each value and apply it in a renderer. This example maps every quarter to a green-to-red scale based on the minimum and maximum across the data, producing a heatmap. The numeric value remains visible in each cell, so the color adds meaning rather than replacing it.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { registerRenderer } from 'handsontable/renderers';
4
import { textRenderer } from 'handsontable/renderers/textRenderer';
5
// register Handsontable's modules
6
registerAllModules();
7
const data = [
8
    ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
9
    ['Vertex Industries', 12.5, 11.9, 13.2, 14],
10
    ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
11
    ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
12
    ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
13
    ['Meridian Retail', 6, 7.3, 8.1, 9.4],
14
];
15
// shade the background from red (low) to green (high); the value stays visible
16
const heatmapRenderer = (instance, td, row, col, prop, value, cellProperties) => {
17
    textRenderer(instance, td, row, col, prop, value, cellProperties);
18
    const amount = Number(value);
19
    if (Number.isFinite(amount)) {
20
        const values = instance.getData()
21
            .flatMap((rowData) => rowData.slice(1))
22
            .map(Number)
23
            .filter((cellValue) => Number.isFinite(cellValue));
24
        const min = Math.min(...values);
25
        const max = Math.max(...values);
26
        const ratio = min === max ? 0.5 : (amount - min) / (max - min);
27
        const hue = Math.round(ratio * 120);
28
        td.style.background = `hsl(${hue}, 75%, 85%)`;
29
        td.style.color = '#1b1b1b';
30
    }
31
};
32
registerRenderer('heatmapRenderer', heatmapRenderer);
33
const ExampleComponent = () => {
34
    return (<HotTable data={data} colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']} licenseKey="non-commercial-and-evaluation" height="auto" columns={[
35
            {},
36
            { renderer: 'heatmapRenderer' },
37
            { renderer: 'heatmapRenderer' },
38
            { renderer: 'heatmapRenderer' },
39
            { renderer: 'heatmapRenderer' },
40
        ]}/>);
41
};
42
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { registerAllModules } from 'handsontable/registry';
3
import { BaseRenderer, registerRenderer } from 'handsontable/renderers';
4
import { textRenderer } from 'handsontable/renderers/textRenderer';
5

6
// register Handsontable's modules
7
registerAllModules();
8

9
const data = [
10
  ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
11
  ['Vertex Industries', 12.5, 11.9, 13.2, 14],
12
  ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
13
  ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
14
  ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
15
  ['Meridian Retail', 6, 7.3, 8.1, 9.4],
16
];
17

18
// shade the background from red (low) to green (high); the value stays visible
19
const heatmapRenderer: BaseRenderer = (instance, td, row, col, prop, value, cellProperties) => {
20
  textRenderer(instance, td, row, col, prop, value, cellProperties);
21

22
  const amount = Number(value);
23

24
  if (Number.isFinite(amount)) {
25
    const values = instance.getData()
26
      .flatMap((rowData) => rowData.slice(1))
27
      .map(Number)
28
      .filter((cellValue) => Number.isFinite(cellValue));
29
    const min = Math.min(...values);
30
    const max = Math.max(...values);
31
    const ratio = min === max ? 0.5 : (amount - min) / (max - min);
32
    const hue = Math.round(ratio * 120);
33

34
    td.style.background = `hsl(${hue}, 75%, 85%)`;
35
    td.style.color = '#1b1b1b';
36
  }
37
};
38

39
registerRenderer('heatmapRenderer', heatmapRenderer);
40

41
const ExampleComponent = () => {
42
  return (
43
    <HotTable
44
      data={data}
45
      colHeaders={['Company', 'Q1', 'Q2', 'Q3', 'Q4']}
46
      licenseKey="non-commercial-and-evaluation"
47
      height="auto"
48
      columns={[
49
        {},
50
        { renderer: 'heatmapRenderer' },
51
        { renderer: 'heatmapRenderer' },
52
        { renderer: 'heatmapRenderer' },
53
        { renderer: 'heatmapRenderer' },
54
      ]}
55
    />
56
  );
57
};
58

59
export default ExampleComponent;

Make conditional formatting accessible

Color alone does not meet WCAG 2.1 AA. Readers with color vision deficiencies, or anyone viewing the grid in high-contrast mode, can miss a signal that relies only on color.

Pair color with a second cue: a symbol, text label, or font weight. In the first example, the loss class adds a marker; in the second, losses appear in parentheses.
In a color scale, keep the underlying value visible so the color stays supplementary.
Verify that text keeps a contrast ratio of at least 4.5:1 against the cell background you apply.

Result

Cells that match your conditions display the configured styles - classes, inline styles, or a color scale - and update automatically as the data changes.

Related guides

Formatting cells

Text alignment

Configuration options

Configuration options

className

cells

renderer