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
/* file: app.component.ts */
2
import { Component, ViewEncapsulation } from '@angular/core';
3
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
4
import Handsontable from 'handsontable/base';
5

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

15
@Component({
16
  selector: 'example1-conditional-formatting',
17
  standalone: true,
18
  imports: [HotTableModule],
19
  template: ` <div>
20
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
21
  </div>`,
22
  styles: `example1-conditional-formatting .handsontable td.company-name {
23
    font-weight: 600;
24
}
25
example1-conditional-formatting .handsontable td.loss {
26
    color: #d81e2c;
27
    background: var(--ht-cell-error-background-color, rgba(216, 30, 44, 0.14));
28
    background: color-mix(in srgb, #d81e2c 16%, var(--ht-background-color, #ffffff));
29
}
30
example1-conditional-formatting .handsontable td.loss::before {
31
    content: "▼ ";
32
}
33
example1-conditional-formatting .handsontable td.strong-quarter {
34
    color: #157a3d;
35
    font-weight: 600;
36
}
37
html[data-theme="dark"] example1-conditional-formatting .handsontable td.loss {
38
    color: #ff5c70;
39
    background: color-mix(in srgb, #ff5c70 22%, var(--ht-background-color, #000000));
40
}
41
html[data-theme="dark"] example1-conditional-formatting .handsontable td.strong-quarter {
42
    color: #22c55e;
43
}
44
`,
45
  encapsulation: ViewEncapsulation.None,
46
})
47
export class AppComponent {
48

49
  readonly data = data;
50

51
  readonly gridSettings: GridSettings = {
52
    colHeaders: ['Company', 'Q1', 'Q2', 'Q3', 'Q4'],
53
    height: 'auto',
54
    columns: [
55
      { className: 'company-name' },
56
      { type: 'numeric' },
57
      { type: 'numeric' },
58
      { type: 'numeric' },
59
      { type: 'numeric' },
60
    ],
61
    cells(row: number, col: number) {
62
      const cellProperties: Handsontable.CellMeta = {};
63

64
      if (col > 0) {
65
        cellProperties.className = '';
66

67
        const value = data[row]?.[col];
68

69
        if (typeof value === 'number' && value < 0) {
70
          cellProperties.className = 'loss';
71
        } else if (typeof value === 'number' && value > 10) {
72
          cellProperties.className = 'strong-quarter';
73
        }
74
      }
75

76
      return cellProperties;
77
    },
78
  };
79
}
80
/* end-file */
81

82

83
/* file: app.config.ts */
84
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
85
import { registerAllModules } from 'handsontable/registry';
86
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
87

88
// register Handsontable's modules
89
registerAllModules();
90

91
export const appConfig: ApplicationConfig = {
92
  providers: [
93
    provideZoneChangeDetection({ eventCoalescing: true }),
94
    {
95
      provide: HOT_GLOBAL_CONFIG,
96
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
97
    },
98
  ],
99
};
100
/* end-file */

1
<div>
2
  <example1-conditional-formatting></example1-conditional-formatting>
3
</div>

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
/* file: app.component.ts */
2
import { Component, ViewEncapsulation } from '@angular/core';
3
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
4
import Handsontable from 'handsontable/base';
5
import { registerRenderer } from 'handsontable/renderers';
6
import { textRenderer } from 'handsontable/renderers/textRenderer';
7

8
// display losses in an accounting format, so color is not the only signal
9
const profitRenderer = (
10
  instance: Handsontable,
11
  td: HTMLTableCellElement,
12
  row: number,
13
  col: number,
14
  prop: string | number,
15
  value: Handsontable.CellValue,
16
  cellProperties: Handsontable.CellProperties
17
) => {
18
  const amount = Number(value);
19

20
  td.classList.remove('loss-cell');
21

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

25
    return;
26
  }
27

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

32
  textRenderer(instance, td, row, col, prop, formatted, cellProperties);
33

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

39
registerRenderer('profitRenderer', profitRenderer);
40

41
@Component({
42
  selector: 'example2-conditional-formatting',
43
  standalone: true,
44
  imports: [HotTableModule],
45
  template: ` <div>
46
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
47
  </div>`,
48
  styles: `example2-conditional-formatting .handsontable td.loss-cell {
49
    color: #d81e2c;
50
    font-weight: 600;
51
}
52
html[data-theme="dark"] example2-conditional-formatting .handsontable td.loss-cell {
53
    color: #ff5c70;
54
}
55
`,
56
  encapsulation: ViewEncapsulation.None,
57
})
58
export class AppComponent {
59

60
  readonly data = [
61
    ['Acme Corp', 4.2, 5.1, -1.3, 6.8],
62
    ['Vertex Industries', 12.5, 11.9, 13.2, 14],
63
    ['Harbor Analytics', -2.4, 0.8, 2.1, 3.5],
64
    ['Summit Logistics', 8.7, -3.2, 4.4, 5.9],
65
    ['Pioneer Foods', 1.1, 1.4, 0.9, -0.5],
66
    ['Meridian Retail', 6, 7.3, 8.1, 9.4],
67
  ];
68

69
  readonly gridSettings: GridSettings = {
70
    colHeaders: ['Company', 'Q1', 'Q2', 'Q3', 'Q4'],
71
    height: 'auto',
72
    columns: [
73
      {},
74
      { renderer: 'profitRenderer' },
75
      { renderer: 'profitRenderer' },
76
      { renderer: 'profitRenderer' },
77
      { renderer: 'profitRenderer' },
78
    ],
79
  };
80
}
81
/* end-file */
82

83

84
/* file: app.config.ts */
85
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
86
import { registerAllModules } from 'handsontable/registry';
87
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
88

89
// register Handsontable's modules
90
registerAllModules();
91

92
export const appConfig: ApplicationConfig = {
93
  providers: [
94
    provideZoneChangeDetection({ eventCoalescing: true }),
95
    {
96
      provide: HOT_GLOBAL_CONFIG,
97
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
98
    },
99
  ],
100
};
101
/* end-file */

1
<div>
2
  <example2-conditional-formatting></example2-conditional-formatting>
3
</div>

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
/* file: app.component.ts */
2
import { Component } from '@angular/core';
3
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
4
import Handsontable from 'handsontable/base';
5
import { registerRenderer } from 'handsontable/renderers';
6
import { textRenderer } from 'handsontable/renderers/textRenderer';
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
// shade the background from red (low) to green (high); the value stays visible
18
const heatmapRenderer = (
19
  instance: Handsontable,
20
  td: HTMLTableCellElement,
21
  row: number,
22
  col: number,
23
  prop: string | number,
24
  value: Handsontable.CellValue,
25
  cellProperties: Handsontable.CellProperties
26
) => {
27
  textRenderer(instance, td, row, col, prop, value, cellProperties);
28

29
  const amount = Number(value);
30

31
  if (Number.isFinite(amount)) {
32
    const values = instance.getData()
33
      .flatMap((rowData) => rowData.slice(1))
34
      .map(Number)
35
      .filter((cellValue) => Number.isFinite(cellValue));
36
    const min = Math.min(...values);
37
    const max = Math.max(...values);
38
    const ratio = min === max ? 0.5 : (amount - min) / (max - min);
39
    const hue = Math.round(ratio * 120);
40

41
    td.style.background = `hsl(${hue}, 75%, 85%)`;
42
    td.style.color = '#1b1b1b';
43
  }
44
};
45

46
registerRenderer('heatmapRenderer', heatmapRenderer);
47

48
@Component({
49
  selector: 'example3-conditional-formatting',
50
  standalone: true,
51
  imports: [HotTableModule],
52
  template: ` <div>
53
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
54
  </div>`,
55
})
56
export class AppComponent {
57

58
  readonly data = data;
59

60
  readonly gridSettings: GridSettings = {
61
    colHeaders: ['Company', 'Q1', 'Q2', 'Q3', 'Q4'],
62
    height: 'auto',
63
    columns: [
64
      {},
65
      { renderer: 'heatmapRenderer' },
66
      { renderer: 'heatmapRenderer' },
67
      { renderer: 'heatmapRenderer' },
68
      { renderer: 'heatmapRenderer' },
69
    ],
70
  };
71
}
72
/* end-file */
73

74

75
/* file: app.config.ts */
76
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
77
import { registerAllModules } from 'handsontable/registry';
78
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
79

80
// register Handsontable's modules
81
registerAllModules();
82

83
export const appConfig: ApplicationConfig = {
84
  providers: [
85
    provideZoneChangeDetection({ eventCoalescing: true }),
86
    {
87
      provide: HOT_GLOBAL_CONFIG,
88
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
89
    },
90
  ],
91
};
92
/* end-file */

1
<div>
2
  <example3-conditional-formatting></example3-conditional-formatting>
3
</div>

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