Cache the output of an expensive cell renderer

In this tutorial, you will make an expensive custom renderer cheap by computing its output once per data record and reusing it on every later render. You will learn why a cache keyed by the td element does not work, how to key it by the record instead, and how to invalidate it when the data changes.

Renderer calls: 0 | Computations: 0

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { baseRenderer, textRenderer } from 'handsontable/renderers';
4

5
registerAllModules();
6

7
/* start:skip-in-preview */
8
const CUSTOMERS = ['Acme Corp', 'Vertex Industries', 'Harbor Goods', 'Alpine Supply Co.', 'Northwind Traders', 'Lumen Retail'];
9
const REGIONS = ['North', 'South', 'East', 'West'];
10

11
// Twelve monthly sales figures per customer, generated deterministically so every load looks the same.
12
function createRows(count) {
13
  const rows = [];
14

15
  for (let index = 0; index < count; index += 1) {
16
    const sales = [];
17
    let seed = (index + 1) * 7919;
18

19
    for (let month = 0; month < 12; month += 1) {
20
      seed = (seed * 48271) % 2147483647;
21
      sales.push(1000 + (seed % 9000));
22
    }
23

24
    rows.push({
25
      id: 1001 + index,
26
      customer: CUSTOMERS[index % CUSTOMERS.length],
27
      region: REGIONS[index % REGIONS.length],
28
      sales,
29
    });
30
  }
31

32
  return rows;
33
}
34
/* end:skip-in-preview */
35

36
const data = createRows(300);
37
const stats = { rendererCalls: 0, computations: 0 };
38

39
// The slow part of the renderer: a text sparkline plus the change from the first to the last month.
40
// It is a pure function -- the same input always gives the same output -- so its result can be cached.
41
function buildTrend(sales) {
42
  const glyphs = '▁▂▃▄▅▆▇█';
43
  const min = Math.min(...sales);
44
  const max = Math.max(...sales);
45
  const range = max - min || 1;
46
  const bars = sales
47
    .map((value) => glyphs[Math.round(((value - min) / range) * (glyphs.length - 1))])
48
    .join('');
49
  const change = Math.round(((sales[sales.length - 1] - sales[0]) / sales[0]) * 100);
50

51
  return `${bars} ${change >= 0 ? '+' : ''}${change}%`;
52
}
53

54
// One cache entry per data record, never per `td`: the grid reuses a `td` for a different record
55
// as you scroll. A WeakMap releases the entry together with the record. Each entry remembers the
56
// input it was computed from, so a replaced array is computed again.
57
const trendCache = new WeakMap();
58

59
const trendRenderer = (instance, td, row, col, prop, value, cellProperties) => {
60
  baseRenderer(instance, td, row, col, prop, value, cellProperties);
61
  stats.rendererCalls += 1;
62

63
  // `row` is a visual index, and `data` is in physical order, so translate before the lookup.
64
  // Read the record from your own array: `getSourceDataAtRow()` returns a copy of the row on
65
  // every call, which can never be a WeakMap key. Keep this closure and the grid's data source
66
  // the same array -- after `updateData()`, point it at the new one.
67
  const record = data[instance.toPhysicalRow(row)];
68
  const sales = value;
69

70
  // A row without a record (a `minSpareRows` row, or one mid-`alter()`) and an empty cell both
71
  // reach the renderer. Neither can be cached: `undefined` is not a valid WeakMap key.
72
  if (!record || !Array.isArray(sales) || sales.length === 0) {
73
    textRenderer(instance, td, row, col, prop, '—', cellProperties);
74

75
    return;
76
  }
77

78
  let entry = trendCache.get(record);
79

80
  if (!entry || entry.input !== sales) {
81
    stats.computations += 1;
82
    entry = { input: sales, output: buildTrend(sales) };
83
    trendCache.set(record, entry);
84
  }
85

86
  // Write through the built-in text renderer rather than setting `td.textContent`. On a row with
87
  // an exact height the engine keeps the cell's content inside a wrapper, and this writes into
88
  // that wrapper instead of replacing it.
89
  textRenderer(instance, td, row, col, prop, entry.output, cellProperties);
90
};
91

92
const container = document.querySelector('#example1');
93
const statsElement = document.querySelector('#render-stats');
94

95
const hot = new Handsontable(container, {
96
  data,
97
  colHeaders: ['ID', 'Customer', 'Region', 'Trend (12 months)'],
98
  columns: [
99
    { data: 'id', type: 'numeric', width: 70, readOnly: true },
100
    { data: 'customer', type: 'text', width: 170 },
101
    { data: 'region', type: 'text', width: 90 },
102
    { data: 'sales', renderer: trendRenderer, width: 190, readOnly: true },
103
  ],
104
  rowHeaders: true,
105
  height: 320,
106
  width: '100%',
107
  autoWrapRow: true,
108
  licenseKey: 'non-commercial-and-evaluation',
109
  // Runs once per draw, scroll draws included, after every cell renderer. Keep DOM writes like
110
  // this one out of the renderer.
111
  afterViewRender() {
112
    statsElement.textContent = `Renderer calls: ${stats.rendererCalls} | Computations: ${stats.computations}`;
113
  },
114
});
115

116
document.querySelector('#render-again-btn').addEventListener('click', () => {
117
  hot.render();
118
});
119

120
document.querySelector('#update-row-btn').addEventListener('click', () => {
121
  // Bring the first row into view, so its renderer runs and the counter shows the single
122
  // recomputation. A cell outside the rendered band is not painted at all.
123
  hot.scrollViewportTo({ row: 0 });
124

125
  // Replace the array instead of changing it in place: the renderer compares inputs by identity.
126
  const nextSales = data[0].sales.map((value, month) => Math.round(value * (1 + month / 10)));
127

128
  hot.setSourceDataAtCell(0, 'sales', nextSales);
129
});

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

5
registerAllModules();
6

7
type OrderRow = {
8
  id: number;
9
  customer: string;
10
  region: string;
11
  sales: number[];
12
};
13

14
/* start:skip-in-preview */
15
const CUSTOMERS = ['Acme Corp', 'Vertex Industries', 'Harbor Goods', 'Alpine Supply Co.', 'Northwind Traders', 'Lumen Retail'];
16
const REGIONS = ['North', 'South', 'East', 'West'];
17

18
// Twelve monthly sales figures per customer, generated deterministically so every load looks the same.
19
function createRows(count: number): OrderRow[] {
20
  const rows: OrderRow[] = [];
21

22
  for (let index = 0; index < count; index += 1) {
23
    const sales: number[] = [];
24
    let seed = (index + 1) * 7919;
25

26
    for (let month = 0; month < 12; month += 1) {
27
      seed = (seed * 48271) % 2147483647;
28
      sales.push(1000 + (seed % 9000));
29
    }
30

31
    rows.push({
32
      id: 1001 + index,
33
      customer: CUSTOMERS[index % CUSTOMERS.length],
34
      region: REGIONS[index % REGIONS.length],
35
      sales,
36
    });
37
  }
38

39
  return rows;
40
}
41
/* end:skip-in-preview */
42

43
const data = createRows(300);
44
const stats = { rendererCalls: 0, computations: 0 };
45

46
// The slow part of the renderer: a text sparkline plus the change from the first to the last month.
47
// It is a pure function -- the same input always gives the same output -- so its result can be cached.
48
function buildTrend(sales: number[]): string {
49
  const glyphs = '▁▂▃▄▅▆▇█';
50
  const min = Math.min(...sales);
51
  const max = Math.max(...sales);
52
  const range = max - min || 1;
53
  const bars = sales
54
    .map((value) => glyphs[Math.round(((value - min) / range) * (glyphs.length - 1))])
55
    .join('');
56
  const change = Math.round(((sales[sales.length - 1] - sales[0]) / sales[0]) * 100);
57

58
  return `${bars} ${change >= 0 ? '+' : ''}${change}%`;
59
}
60

61
// One cache entry per data record, never per `td`: the grid reuses a `td` for a different record
62
// as you scroll. A WeakMap releases the entry together with the record. Each entry remembers the
63
// input it was computed from, so a replaced array is computed again.
64
const trendCache = new WeakMap<OrderRow, { input: number[]; output: string }>();
65

66
const trendRenderer: BaseRenderer = (instance, td, row, col, prop, value, cellProperties) => {
67
  baseRenderer(instance, td, row, col, prop, value, cellProperties);
68
  stats.rendererCalls += 1;
69

70
  // `row` is a visual index, and `data` is in physical order, so translate before the lookup.
71
  // Read the record from your own array: `getSourceDataAtRow()` returns a copy of the row on
72
  // every call, which can never be a WeakMap key. Keep this closure and the grid's data source
73
  // the same array -- after `updateData()`, point it at the new one.
74
  const record = data[instance.toPhysicalRow(row)];
75
  const sales = value;
76

77
  // A row without a record (a `minSpareRows` row, or one mid-`alter()`) and an empty cell both
78
  // reach the renderer. Neither can be cached: `undefined` is not a valid WeakMap key.
79
  if (!record || !Array.isArray(sales) || sales.length === 0) {
80
    textRenderer(instance, td, row, col, prop, '—', cellProperties);
81

82
    return;
83
  }
84

85
  let entry = trendCache.get(record);
86

87
  if (!entry || entry.input !== sales) {
88
    stats.computations += 1;
89
    entry = { input: sales, output: buildTrend(sales) };
90
    trendCache.set(record, entry);
91
  }
92

93
  // Write through the built-in text renderer rather than setting `td.textContent`. On a row with
94
  // an exact height the engine keeps the cell's content inside a wrapper, and this writes into
95
  // that wrapper instead of replacing it.
96
  textRenderer(instance, td, row, col, prop, entry.output, cellProperties);
97
};
98

99
const container = document.querySelector<HTMLElement>('#example1')!;
100
const statsElement = document.querySelector<HTMLElement>('#render-stats')!;
101

102
const hot = new Handsontable(container, {
103
  data,
104
  colHeaders: ['ID', 'Customer', 'Region', 'Trend (12 months)'],
105
  columns: [
106
    { data: 'id', type: 'numeric', width: 70, readOnly: true },
107
    { data: 'customer', type: 'text', width: 170 },
108
    { data: 'region', type: 'text', width: 90 },
109
    { data: 'sales', renderer: trendRenderer, width: 190, readOnly: true },
110
  ],
111
  rowHeaders: true,
112
  height: 320,
113
  width: '100%',
114
  autoWrapRow: true,
115
  licenseKey: 'non-commercial-and-evaluation',
116
  // Runs once per draw, scroll draws included, after every cell renderer. Keep DOM writes like
117
  // this one out of the renderer.
118
  afterViewRender() {
119
    statsElement.textContent = `Renderer calls: ${stats.rendererCalls} | Computations: ${stats.computations}`;
120
  },
121
});
122

123
document.querySelector('#render-again-btn')!.addEventListener('click', () => {
124
  hot.render();
125
});
126

127
document.querySelector('#update-row-btn')!.addEventListener('click', () => {
128
  // Bring the first row into view, so its renderer runs and the counter shows the single
129
  // recomputation. A cell outside the rendered band is not painted at all.
130
  hot.scrollViewportTo({ row: 0 });
131

132
  // Replace the array instead of changing it in place: the renderer compares inputs by identity.
133
  const nextSales = data[0].sales.map((value, month) => Math.round(value * (1 + month / 10)));
134

135
  hot.setSourceDataAtCell(0, 'sales', nextSales);
136
});

1
<div class="example-controls-container">
2
  <div class="controls">
3
    <button id="render-again-btn" type="button">Render again</button>
4
    <button id="update-row-btn" type="button">Update the first row</button>
5
  </div>
6
</div>
7
<div id="example1"></div>
8
<p id="render-stats" style="margin: 8px 0 0; font-size: 13px; color: #666;">Renderer calls: 0 | Computations: 0</p>

Overview

Difficulty: Intermediate Time: ~15 minutes

Handsontable calls a cell renderer for every rendered cell on every render — after each scroll, sort, edit, or render() call. A renderer that computes something slow from the cell’s data — a chart, a parsed document, a formatted summary — repeats that work for the same record again and again. A cache fixes that, but only if you pick the right key.

What you’ll build

An order grid with 300 customers, where the Trend column turns twelve monthly sales figures into a text sparkline and a percent change. The grid:

Counts renderer calls and computations, and shows both counters under the grid.
Computes each record’s trend once, however often the grid renders.
Recomputes a record only when its sales array is replaced.
Has a Render again button, which repaints the grid without a single new computation, and an Update the first row button, which triggers exactly one.

Before you begin

You need a working Handsontable installation. See the Getting started guide.
Read Understanding rendering to know what a render covers and why direct DOM changes disappear.
You should be familiar with custom renderer functions.

Step 1 — Write the slow computation as a plain function

Keep the expensive work in a function that takes the data in and returns the output, with nothing else in between:

1
function buildTrend(sales) {
2
  const glyphs = '▁▂▃▄▅▆▇█';
3
  const min = Math.min(...sales);
4
  const max = Math.max(...sales);
5
  const range = max - min || 1;
6
  const bars = sales
7
    .map((value) => glyphs[Math.round(((value - min) / range) * (glyphs.length - 1))])
8
    .join('');
9
  const change = Math.round(((sales[sales.length - 1] - sales[0]) / sales[0]) * 100);
10

11
  return `${bars} ${change >= 0 ? '+' : ''}${change}%`;
12
}

What’s happening: buildTrend() is a pure function. The same input always gives the same output, and it reads nothing from the grid or the DOM. That is what makes its result safe to cache. In this recipe the computation is small so the demo stays responsive; in your app it is whatever costs the most in your renderer.

Step 2 — Count what the renderer does

Two counters make the effect of the cache visible:

1
const stats = { rendererCalls: 0, computations: 0 };

The renderer increments rendererCalls on every call and computations only when it runs buildTrend(). The afterViewRender hook writes both counters under the grid:

1
afterViewRender() {
2
  statsElement.textContent = `Renderer calls: ${stats.rendererCalls} | Computations: ${stats.computations}`;
3
}

Why afterViewRender, and why not write the counters from inside the renderer? afterViewRender runs once per draw, after every cell renderer has finished, and it also runs for the draws that scrolling triggers — which afterRender does not report. A renderer runs once per cell, so a DOM write there would run hundreds of times per draw.

Step 3 — Key the cache by the data record, not by the `td`

1
const trendCache = new WeakMap();

The cache is a WeakMap whose keys are the row objects of your data source. It holds one entry per record, and each entry remembers the input it was computed from:

1
{ input: sales, output: buildTrend(sales) }

Why not key the cache by the td element? Handsontable renders only the visible cells plus a small buffer, and it keeps a fixed set of td elements for them. A vertical scroll keeps a row’s td elements with the row while the row stays rendered, but nothing else does: a horizontal scroll, a row that leaves the rendered area and comes back, and any scroll in a grid that scrolls with the page all hand the record a different td. A cache keyed by the td — a WeakMap of td to output, or a property set on the element — therefore misses on every one of those, and the expensive work runs again for cells that were computed a moment ago. The record is the thing that stays the same between renders, so it is the key.

Why a WeakMap? When a record leaves the data set and nothing else references it, its cache entry is released with it. A plain Map would keep every record alive.

Step 4 — Use the cache in the renderer

1
const trendRenderer = (instance, td, row, col, prop, value, cellProperties) => {
2
  baseRenderer(instance, td, row, col, prop, value, cellProperties);
3
  stats.rendererCalls += 1;
4

5
  const record = data[instance.toPhysicalRow(row)];
6
  const sales = value;
7

8
  if (!record || !Array.isArray(sales) || sales.length === 0) {
9
    textRenderer(instance, td, row, col, prop, '—', cellProperties);
10

11
    return;
12
  }
13

14
  let entry = trendCache.get(record);
15

16
  if (!entry || entry.input !== sales) {
17
    stats.computations += 1;
18
    entry = { input: sales, output: buildTrend(sales) };
19
    trendCache.set(record, entry);
20
  }
21

22
  textRenderer(instance, td, row, col, prop, entry.output, cellProperties);
23
};

What’s happening:

baseRenderer() applies the standard cell classes, so the cell still reacts to readOnly, validation, and the rest of the cell meta.
row is a visual index, and your data array is in physical order, so toPhysicalRow() translates it before the lookup. Without the translation, sorting the grid would pair a cell with the wrong record. Read the record from your own array: getSourceDataAtRow() returns a copy of the row on every call, so a WeakMap keyed by its result never hits.
The guard covers the two rows that have no record to key on: a spare row added by minSpareRows, and a row the renderer sees while alter() is still running. undefined is not a valid WeakMap key, so caching one throws and takes the whole draw down with it. An empty cell is caught by the same check.
value is the cell’s value — here, the sales array, handed to the renderer as the same array that sits in the record, not a copy. If the record has an entry and the entry was computed from this same array, the renderer reuses the output. Otherwise it computes, stores, and moves on.
The renderer always writes the cell, on the cached path as well as the computed one, because the grid resets a td before it runs a renderer. Only what the renderer writes back survives.
The write goes through the built-in textRenderer rather than td.textContent = …. On a row whose height is exact, the engine keeps the cell’s content inside a wrapper it reuses between draws. textContent would replace that wrapper, and the engine would build it again on the next draw. textRenderer writes into it instead.

The renderer closes over data, so keep that binding current. This renderer indexes the same array it gave the grid. If you later swap the data set with updateData() or loadData(), the grid holds the new array while the closure still points at the old one, and every lookup returns a stale record or undefined — with no error. Point the closure at the new array in the same step, or key the cache by the cell value instead, which needs no closure at all (see Variations).

Attach the renderer to the column:

1
columns: [
2
  { data: 'id', type: 'numeric', width: 70, readOnly: true },
3
  { data: 'customer', type: 'text', width: 170 },
4
  { data: 'region', type: 'text', width: 90 },
5
  { data: 'sales', renderer: trendRenderer, width: 190, readOnly: true },
6
],

Step 5 — Invalidate when the data changes

The entry stores the input it was computed from, so the cache invalidates itself when the input is replaced. The Update the first row button replaces the first record’s sales array:

1
const nextSales = data[0].sales.map((value, month) => Math.round(value * (1 + month / 10)));
2

3
hot.setSourceDataAtCell(0, 'sales', nextSales);

The button first calls scrollViewportTo({ row: 0 }), because a cell outside the rendered band is not painted at all — without it, a reader who has scrolled away sees no counter change. setSourceDataAtCell() then writes the new array into the record and renders the grid. On that render, entry.input !== sales is true for that one record, and computations grows by one. Every other cell hits the cache.

Replace, do not mutate. The renderer compares inputs by identity. A change made in place, such as data[0].sales[11] = 5000, leaves the array’s identity unchanged, so the cached output stays stale. Either replace the array, as above, or delete the entry by hand before you render:

1
trendCache.delete(data[0]);
2
hot.render();

The same rule applies to a primitive value: the input !== value check compares two strings or two numbers by value, so an edited cell is recomputed on its own.

How it works — complete flow

First render. The renderer runs for every rendered cell of the Trend column, and computations equals the number of rendered rows: every record is new to the cache.
Scroll down. The renderer runs again for every cell in the new viewport, but computations grows only by the rows that were not rendered before.
Scroll back up. rendererCalls keeps growing; computations does not move. Every record on screen is already in the cache.
Render again. rendererCalls grows by the number of rendered cells; computations stays where it was.
Update the first row. The grid scrolls back to the top and computations grows by exactly one.

Variations

The value is an object. When the cell’s value is itself an object or an array, you can key the WeakMap by the value and skip the record lookup: the grid hands the renderer the value itself, not a copy. A replaced value is then a new key, and the old entry is released with the old value.
The renderer mounts a component. If your renderer mounts a framework component or builds a large DOM subtree, let the td own the container. On each call, reuse the container the cell already holds and update it with the record the cell now shows; create one only for a cell that has none. A vertical scroll keeps a row’s td elements with the row, so the containers of the rows that stay rendered are not touched at all, and a row that enters takes over the container a leaving row left behind. The Angular wrapper’s HotCellRendererComponent renders its component cells this way: one component per td, its inputs updated on every call. Three rules make that safe:
1. Update in place, never rebuild. Set the component’s inputs, or rewrite the subtree’s text and attributes, from the record the renderer receives. Tearing the container down and mounting a new one on every call is the cost you are trying to avoid.
2. Key by the td, not by the coordinates. A container keyed by row and column has to be moved between cells as the band moves, and a cell in a frozen column is drawn twice, once in the master table and once in the overlay clone, so one container cannot serve both. A container owned by the td has one parent for its whole life.
3. Make the container the cell’s only child. Clear the cell before you append. A container placed next to whatever the cell already holds leaves the cell with two children, and the engine’s own content wrapper is then rebuilt on every draw.
Hold the containers in a WeakMap keyed by the td, so a cell element the grid drops releases its container with it.
Skip the cells that did not change. The renderMode option set to 'onChange' lets a render skip cells whose data, meta, and position did not change since their last paint. A vertical scroll then paints only the rows that enter the rendered area, plus the cells of merged blocks; a horizontal scroll, and any scroll in a grid that scrolls with the page, still repaint the rendered cells, so the cache in this recipe is still what saves the computation there. The two combine well: the option removes the renderer call, the cache removes the computation.

What you learned

A renderer runs for every rendered cell on every render, so a slow computation inside it runs far more often than the data changes.
A td follows its row only through a vertical scroll; a horizontal scroll and a row that comes back into view give the record another td, so a td is the wrong cache key for a computed value. The data record, or the cell coordinates, is the right one.
A WeakMap keyed by the record releases entries together with the records.
Storing the input next to the output makes the cache invalidate itself when the input is replaced. In-place mutation keeps the same identity, so it needs an explicit delete().
How to translate a visual row index to a physical one before reading the data source.
Why a renderer needs a guard for a row with no record: a WeakMap cannot take undefined as a key, and a throw inside a renderer takes the whole draw down.

Next steps

If your renderer only formats the value — units, dates, text transforms — use the valueFormatter option instead of a custom renderer.
Reduce the number of renders with batch() when you change many cells at once. See Batch operations.
Skip the cells that did not change, on renders and on vertical scrolls, with renderMode: 'onChange'.
For a renderer that draws an SVG chart in the cell, see the Sparkline cell renderer recipe.