Sparkline cell renderer

In this tutorial, you will build a custom cell renderer that draws an inline SVG bar chart from an array of numbers in each cell. You will learn how to register a named renderer with registerRenderer, bundle it into a cell type with registerCellType, and assign it to a read-only sparkline column.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { registerRenderer, baseRenderer } from 'handsontable/renderers';
4
import { registerCellType } from 'handsontable/cellTypes';
5

6
registerAllModules();
7

8
const SLOT = 10;
9
const GAP = 2;
10
const VIEW_HEIGHT = 100;
11
const WEEK_KEYS = ['w1', 'w2', 'w3', 'w4', 'w5'];
12
const VIEW_WIDTH = WEEK_KEYS.length * SLOT - GAP;
13

14
// Returns null for invalid/non-numeric values, preserving each slot's position.
15
function toSlots(rowData) {
16
  return WEEK_KEYS.map((key) => {
17
    const value = rowData?.[key];
18
    const n = typeof value === 'number' ? value : Number(value);
19
    return Number.isFinite(n) ? n : null;
20
  });
21
}
22

23
// Inline SVG bar chart generated from the row's w1-w5 values.
24
const sparklineRenderer = (instance, td, row, col, prop, value, cellProperties) => {
25
  baseRenderer(instance, td, row, col, prop, value, cellProperties);
26

27
  const sourceRow = instance.getSourceDataAtRow(row);
28
  const slots = toSlots(sourceRow);
29
  const validNumbers = slots.filter((n) => n !== null);
30

31
  if (validNumbers.length === 0) {
32
    td.textContent = '—';
33
    td.title = 'No data';
34
    return;
35
  }
36

37
  const rowMax = validNumbers.reduce((m, n) => Math.max(m, Math.abs(n)), 0);
38

39
  if (rowMax === 0) {
40
    td.textContent = '—';
41
    td.title = 'All values are zero';
42
    return;
43
  }
44

45
  const average = validNumbers.reduce((sum, n) => sum + n, 0) / validNumbers.length;
46
  const rects = slots
47
    .map((n, i) => {
48
      if (n === null) return '';
49
      const barHeight = (Math.abs(n) / rowMax) * VIEW_HEIGHT;
50
      const x = i * SLOT;
51
      const y = VIEW_HEIGHT - barHeight;
52
      const w = SLOT - GAP;
53
      const fill = n >= average ? '#16a34a' : '#dc2626';
54
      return `<rect x="${x}" y="${y}" width="${w}" height="${barHeight}" fill="${fill}"/>`;
55
    })
56
    .join('');
57

58
  td.innerHTML = `<svg width="100%" height="100%" viewBox="0 0 ${VIEW_WIDTH} ${VIEW_HEIGHT}" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">${rects}</svg>`;
59
  td.removeAttribute('title');
60
};
61

62
registerRenderer('sparklineBar', sparklineRenderer);
63
registerCellType('sparklineBar', { renderer: sparklineRenderer });
64

65
/* start:skip-in-preview */
66
const data = [
67
  { product: 'Desk lamp', w1: 4, w2: 8, w3: 2, w4: 9, w5: 5 },
68
  { product: 'Monitor arm', w1: 1, w2: 1, w3: 0, w4: 0, w5: 0 },
69
  { product: 'USB hub', w1: null, w2: null, w3: null, w4: null, w5: null },
70
  { product: 'Mouse', w1: undefined, w2: undefined, w3: 3, w4: 5, w5: 2 },
71
  { product: 'Keyboard', w1: 3, w2: 6, w3: 7, w4: 4, w5: 8 },
72
  { product: 'Webcam', w1: 0, w2: 0, w3: 0, w4: 0, w5: 0 },
73
];
74
/* end:skip-in-preview */
75

76
const container = document.querySelector('#example1');
77

78
new Handsontable(container, {
79
  data,
80
  rowHeaders: true,
81
  rowHeights: 44,
82
  colHeaders: ['Product', 'W1', 'W2', 'W3', 'W4', 'W5', 'Sparkline'],
83
  licenseKey: 'non-commercial-and-evaluation',
84
  height: 'auto',
85
  width: '100%',
86
  columns: [
87
    { data: 'product', type: 'text', width: 100, readOnly: true },
88
    { data: 'w1', type: 'numeric', width: 48 },
89
    { data: 'w2', type: 'numeric', width: 48 },
90
    { data: 'w3', type: 'numeric', width: 48 },
91
    { data: 'w4', type: 'numeric', width: 48 },
92
    { data: 'w5', type: 'numeric', width: 48 },
93
    {
94
      data: null,
95
      width: 160,
96
      type: 'sparklineBar',
97
      className: 'htMiddle sparkline-cell',
98
      readOnly: true,
99
    },
100
  ],
101
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { BaseRenderer, registerRenderer, baseRenderer } from 'handsontable/renderers';
4
import { registerCellType } from 'handsontable/cellTypes';
5

6
registerAllModules();
7

8
const SLOT = 10;
9
const GAP = 2;
10
const VIEW_HEIGHT = 100;
11
const WEEK_KEYS = ['w1', 'w2', 'w3', 'w4', 'w5'] as const;
12
const VIEW_WIDTH = WEEK_KEYS.length * SLOT - GAP;
13

14
// Returns null for invalid/non-numeric values, preserving each slot's position.
15
function toSlots(rowData: Record<string, unknown> | null): (number | null)[] {
16
  return WEEK_KEYS.map((key) => {
17
    const value = rowData?.[key];
18
    const n = typeof value === 'number' ? value : Number(value);
19
    return Number.isFinite(n) ? n : null;
20
  });
21
}
22

23
// Inline SVG bar chart generated from the row's w1-w5 values.
24
const sparklineRenderer: BaseRenderer = (
25
  instance,
26
  td,
27
  row,
28
  col,
29
  prop,
30
  value,
31
  cellProperties
32
) => {
33
  baseRenderer(instance, td, row, col, prop, value, cellProperties);
34

35
  const sourceRow = instance.getSourceDataAtRow(
36
    row
37
  ) as Record<string, unknown> | null;
38
  const slots = toSlots(sourceRow);
39
  const validNumbers = slots.filter((n): n is number => n !== null);
40

41
  if (validNumbers.length === 0) {
42
    td.textContent = '—';
43
    td.title = 'No data';
44
    return;
45
  }
46

47
  const rowMax = validNumbers.reduce((m, n) => Math.max(m, Math.abs(n)), 0);
48

49
  if (rowMax === 0) {
50
    td.textContent = '—';
51
    td.title = 'All values are zero';
52
    return;
53
  }
54

55
  const average =
56
    validNumbers.reduce((sum, n) => sum + n, 0) / validNumbers.length;
57
  const rects = slots
58
    .map((n, i) => {
59
      if (n === null) return '';
60
      const barHeight = (Math.abs(n) / rowMax) * VIEW_HEIGHT;
61
      const x = i * SLOT;
62
      const y = VIEW_HEIGHT - barHeight;
63
      const w = SLOT - GAP;
64
      const fill = n >= average ? '#16a34a' : '#dc2626';
65
      return `<rect x="${x}" y="${y}" width="${w}" height="${barHeight}" fill="${fill}"/>`;
66
    })
67
    .join('');
68

69
  td.innerHTML = `<svg width="100%" height="100%" viewBox="0 0 ${VIEW_WIDTH} ${VIEW_HEIGHT}" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">${rects}</svg>`;
70
  td.removeAttribute('title');
71
};
72

73
registerRenderer('sparklineBar', sparklineRenderer);
74
registerCellType('sparklineBar', { renderer: sparklineRenderer });
75

76
/* start:skip-in-preview */
77
const data = [
78
  { product: 'Desk lamp', w1: 4, w2: 8, w3: 2, w4: 9, w5: 5 },
79
  { product: 'Monitor arm', w1: 1, w2: 1, w3: 0, w4: 0, w5: 0 },
80
  { product: 'USB hub', w1: null, w2: null, w3: null, w4: null, w5: null },
81
  { product: 'Mouse', w1: undefined, w2: undefined, w3: 3, w4: 5, w5: 2 },
82
  { product: 'Keyboard', w1: 3, w2: 6, w3: 7, w4: 4, w5: 8 },
83
  { product: 'Webcam', w1: 0, w2: 0, w3: 0, w4: 0, w5: 0 },
84
];
85
/* end:skip-in-preview */
86

87
const container = document.querySelector('#example1')!;
88

89
new Handsontable(container, {
90
  data,
91
  rowHeaders: true,
92
  rowHeights: 44,
93
  colHeaders: ['Product', 'W1', 'W2', 'W3', 'W4', 'W5', 'Sparkline'],
94
  licenseKey: 'non-commercial-and-evaluation',
95
  height: 'auto',
96
  width: '100%',
97
  columns: [
98
    { data: 'product', type: 'text', width: 100, readOnly: true },
99
    { data: 'w1', type: 'numeric', width: 48 },
100
    { data: 'w2', type: 'numeric', width: 48 },
101
    { data: 'w3', type: 'numeric', width: 48 },
102
    { data: 'w4', type: 'numeric', width: 48 },
103
    { data: 'w5', type: 'numeric', width: 48 },
104
    {
105
      data: null,
106
      width: 160,
107
      type: 'sparklineBar',
108
      className: 'htMiddle sparkline-cell',
109
      readOnly: true,
110
    },
111
  ],
112
});

1
/* Keep sparkline cells vertically centered and tall enough for the SVG */
2
#example1 .handsontable td.sparkline-cell {
3
  vertical-align: middle;
4
}

Overview

This recipe shows how to edit weekly values in table cells and render a mini bar chart with inline SVG in a separate sparkline column. No charting library is required.

Difficulty: Beginner
Time: ~10 minutes
Libraries: None

What you’ll build

A named renderer registered with registerRenderer and bundled as a sparklineBar cell type via registerCellType.
Bars scaled to a fixed global scale — the tallest bar across the entire dataset fills the full SVG height. Editing one cell does not change proportions in other rows.
Each row always shows five bar slots. A slot is left empty when its source value is missing or non-numeric.
Safe handling when a row has no valid values or when every value in the dataset is zero.
Optional coloring: green when a value is at or above the row average, red when below.
Interactive behavior — when you edit W1-W5, Handsontable re-renders the sparkline SVG for that row.

Call the base renderer first

Always call baseRenderer before you change the cell content. That keeps read-only styling, validation classes, and ARIA attributes consistent with other cells.
Map cell values to slots

Use toSlots to map each of the five week keys to either a number or null. Returning null instead of filtering keeps the slot count fixed at five so the SVG viewBox width never changes. Invalid or missing values produce an empty slot rather than a shifted bar.
Compute a global scale

Call getGlobalMax to find the largest absolute value across all rows in the dataset. All bars share this scale, so editing a single cell only changes that row’s bar heights — not the proportions in every other row. A global max of zero means every value in the dataset is zero, which is handled as an edge case.
Build the SVG

Use one <rect> per valid slot. Bar height is (abs(value) / globalMax) * viewBoxHeight. The viewBox is always (5 × SLOT - GAP) wide, so empty slots stay as blank space at their correct position. Average the valid numbers in the row to pick fill colors.
Register the renderer and cell type

Use registerRenderer('sparklineBar', sparklineRenderer) to name the renderer, then registerCellType('sparklineBar', { renderer: 'sparklineBar' }) to bundle it as a cell type. Set type: 'sparklineBar' on the sparkline column instead of renderer: 'sparklineBar'. Keep that column readOnly and leave W1-W5 editable so each edit triggers a fresh render.

Edge cases covered

Case	Behavior
`null` / `undefined` / non-numeric week values	Empty slot — bar is omitted, neighboring bars keep their positions
All week values missing in a row	Em dash, tooltip “No data”
All values zero across the entire dataset	Em dash, tooltip “All values are zero”
Mixed valid numbers	Bars scale to the global maximum absolute value

What you learned

How to register a named custom renderer with registerRenderer and bundle it as a reusable cell type with registerCellType.
How to compute a global scale from the full dataset so bars stay proportional across rows when data changes.
How to preserve fixed slot positions by returning null for invalid values instead of filtering them out.
How to handle edge cases — null values, all-zero datasets, and empty rows — so the renderer degrades gracefully to a placeholder instead of crashing.
How keeping the sparkline column readOnly while leaving the data columns editable triggers a fresh render with updated bars after each edit.

Next steps

Explore conditional row coloring for a simpler styling approach using CSS classes instead of custom SVG output.
Read the cell renderer guide for the full renderer API and lifecycle.

Cell renderer - renderer API and registration patterns.

Sparkline cell renderer

Overview

What you’ll build

Call the base renderer first

Map cell values to slots

Compute a global scale

Build the SVG

Register the renderer and cell type

Edge cases covered

What you learned

Next steps

Related