Understanding rendering
Learn what a render does, which cells it covers, what it costs, and when you need to call render() yourself.
Background
Handsontable DataGrid does not keep every cell of your data set in the DOM. It renders only the part of the grid that you can see, plus a small buffer around it. As you scroll, it reuses the same DOM elements for new cells. This is called row virtualization and column virtualization, and it is what lets the grid hold hundreds of thousands of records without freezing the browser.
A render is the step that brings those DOM elements back in sync with your data and your configuration. Handsontable runs it for you at the right moments, so most applications never call render() at all. You need it when you change something that Handsontable cannot detect on its own — cell metadata, or a value outside the grid that one of your renderers reads.
How it works
What a render does
A render recalculates the grid’s layout, redraws its cells, and applies the result to the DOM. For every cell it draws, Handsontable:
- Resets the cell’s
tdelement to a blank state. - Resolves the cell’s metadata, which includes running the
cellsfunction if you defined one. - Runs the cell’s renderer, which writes the value, the CSS classes, and any other markup.
A render redraws the grid in place. It does not change your data, your selection, or your scroll position.
What a render covers
A render covers the cells that are currently rendered, not your whole data set. That is the viewport plus the buffer set by viewportRowRenderingOffset and viewportColumnRenderingOffset.
So on a grid of 100,000 rows showing 30 of them, a render redraws those 30 rows and the buffer around them. It does not touch the other 99,970.
Two options change this. If you set renderAllRows or renderAllColumns to true, you turn virtualization off on that axis, every row or column lives in the DOM, and a render then covers all of them.
What a render costs
The cost of a render scales with the number of cells it draws, multiplied by the work your renderers and your cells function do for each of them. The number of records you hold is not what drives it.
This has two consequences:
- A render on a grid with 1,000,000 records costs about the same as a render on a grid with 100 records, as long as both show the same number of cells. (Handsontable still keeps some per-record caches, such as row heights, so a render that has to rebuild one of them costs more.)
- Work you put inside a renderer or inside the
cellsfunction runs again on every render, for every drawn cell. A small cost there adds up quickly. See Avoid thecellsoption when possible.
What makes an application slow is rarely one render. It is many renders in a row, which is what batching exists to prevent.
When Handsontable renders on its own
Handsontable picks the moments for you. It renders after every CRUD operation, while you scroll, when rows or columns are hidden or trimmed, and at the end of updateSettings(). Anything that changes the grid through the Handsontable API is covered.
When you call render() yourself
Call render() when you change something that Handsontable cannot detect. The common case is setCellMeta(), which writes to the cell’s metadata but does not repaint the grid:
hot.setCellMeta(0, 0, 'className', 'my-highlight');hot.render(); // without this, the class is stored but not visibleBecause setCellMeta() never renders on its own, several calls followed by one render() already cost exactly one render:
hot.setCellMeta(0, 0, 'className', 'my-highlight');hot.setCellMeta(1, 0, 'readOnly', true);hot.setCellMeta(2, 0, 'type', 'date');hot.render(); // one render applies all three changesThe same applies when an external condition that your renderer reads has changed, but your data has not. If your renderer colors rows based on a value held outside the grid, update that value and then call render().
Why direct DOM changes disappear
Handsontable reuses td elements as you scroll, sort, and filter, so before it paints a cell with a renderer it resets part of the element: the cell’s class attribute, its inline style, its dir attribute, and its accessibility attributes are cleared. Other things stay on the reused cell: most data-* attributes, title, child nodes, and properties your code assigns to the element. These then show up on whichever record the cell displays next. Changes made outside a renderer do not survive lists the exact rules.
Treat a class, style, or accessibility change written onto a td from outside a renderer as lost at the next render. In a renderer, empty the cell and set or remove every attribute you use on every render, so nothing from the previous record remains. For an example, see Add a tooltip to a cell.
This is why a change you make straight on the DOM disappears at the next render:
// Do not do this. The next render removes the class.hot.getCell(0, 0).classList.add('my-highlight');Set the class through the cell’s metadata instead, so that a renderer reapplies it every time:
hot.setCellMeta(0, 0, 'className', 'my-highlight');hot.render();If you need markup that no option covers, write a custom renderer. A renderer runs on every render, so what it writes is always reapplied. (Under renderMode: 'onChange' it runs whenever the cell changed, which for markup written from the cell’s value and meta is the same thing.)
The same reuse rules out the td as a cache key: after a scroll it shows a different record, so a WeakMap of td to a computed value misses on almost every call. Key a renderer’s cache by the data record or by the cell coordinates instead. The Cache the output of an expensive cell renderer recipe shows the pattern.
Observe renders
Two hooks let you see the rendering cycle:
beforeRenderfires before the cells are drawn.afterRenderfires after they are drawn.
Both receive an isForced argument. It tells you what triggered the render, not how much work it did. It is true for a render that render(), a settings change, or a data change triggered, and false for one triggered by something lighter, such as a selection move. A false render can still redraw cells: if the selection moves to a row or column that is not rendered yet, Handsontable draws the new band.
hot.addHook('afterRender', (isForced) => { console.log(isForced ? 'forced render' : 'light render');});Scrolling does not fire either hook. The engine repaints the viewport directly while you scroll, without going through the render path these hooks observe.
Use these hooks to count renders while you profile. If you see many in a row for one user action, batch that action.
Trade-offs
Skip the cells that did not change
By default, every render repaints every rendered cell, and there is no API to repaint one cell on its own. Virtualization keeps the drawn cell count low and roughly constant, so a render is bounded by the size of the viewport rather than the size of your data, and for the built-in renderers a render is cheap. The lever you have is the number of renders. Use batch() to keep that number down.
When your renderers are slow, the size of a render matters too. The renderMode option lets a render skip the cells that did not change since their last paint:
// skip unchanged cells in the whole gridrenderMode: 'onChange',
// or only in the column that carries the slow renderercolumns: [ { data: 'chart', renderer: chartRenderer, renderMode: 'onChange' }, { data: 'name' },],Under 'onChange', a cell is painted only when the element it lands in showed something else after its last paint: another cell (its row scrolled out of the rendered area and another row took the element), another value, another renderer, a changed cell meta, or a structural change of the grid such as a sort, a filter, an inserted row, a data reload, or a settings update. Everything the grid can see is covered, including a formula whose dependency changed, a validation result, a comment, and a merged cell.
A vertical scroll keeps the elements of the rows that stay rendered, so it paints only the rows that enter the rendered area. A renderer that caches per element (a framework component attached to the cell element, for example) keeps its cache across such a scroll as well. In a grid with merged cells, the cells of the merged blocks repaint on every scroll too, because a block’s span is clamped to the rendered area; the other cells are skipped as usual. A horizontal scroll repaints the rendered cells, and so does any scroll in a grid that scrolls with the page instead of inside its own box.
Some changes are invisible to the grid, because nothing in it sees them:
- A meta object mutated directly, such as
hot.getCellMeta(row, col).readOnly = true, including inside thebeforeGetCellMetaandafterGetCellMetahooks. UsesetCellMeta()or thecellsfunction instead; both are detected. - A value object mutated in place. The grid compares values by identity, so
row.checked = trueon an object the cell already showed does not count. - State outside the grid that a renderer reads, such as a theme flag or a store.
- A renderer that reads the data of other cells. The built-in checkbox renderer does this when
label.propertypoints at another column: editing that column does not repaint the checkbox cell. - A renderer that reads where the rendered area starts or ends, through
getFirstRenderedVisibleRow()or its siblings. A vertical scroll keeps such a cell as it is, because the cell’s own row and value did not change.
A cells function result is compared value by value. Return the same references for an unchanged result: a renderer function created on every call counts as a change on every render.
For such cells, keep renderMode: 'always' (the option cascades, so one column or one cell can opt out), or mark the cell before you render:
theme = 'dark';hot.markCellChanged(0, 0); // paint this cell on the next render, whatever its renderModehot.render();
hot.markAllCellsChanged(); // paint every cell on the next renderhot.render();The same applies to a cell meta object you change directly rather than through setCellMeta(): hot.getCellMeta(0, 0).readOnly = true is not a change the grid sees. Write through setCellMeta(), which is the documented way in every mode.
render(), updateSettings(), and refreshDimensions()
Three methods repaint the grid, and they are not interchangeable.
| Method | What it does | Use it when |
|---|---|---|
render() | Redraws the rendered cells. Leaves the configuration alone. | Cell metadata or an external value your renderer reads has changed. |
updateSettings() | Applies new configuration options, reinitializes the affected plugins, then renders. | An option, a column definition, or the data source has changed. |
refreshDimensions() | Re-measures the container, then resizes the grid’s elements and renders when the size changed. With a cell editor open, it also moves the editor onto its cell, and scrolls the cell into view first when it was not fully visible. | The container was resized while the grid was hidden. |
Pick the narrowest one that does the job. updateSettings() does the most work of the three, so do not reach for it when a render is enough.
You rarely need refreshDimensions() at all: Handsontable calls it for you on a window resize and through a ResizeObserver on the container. The gap is a container resized while the grid is hidden, inside a display: none tab or accordion. The observer callback is skipped there, so call the method yourself once the grid becomes visible again. A web font that loads after the grid renders needs no call either: Handsontable re-measures the grid itself, without going through refreshDimensions(), so the beforeRefreshDimensions and afterRefreshDimensions hooks do not fire for it. On a grid with no fixed height — one that scrolls with the page — the method renders on every call, even when the size did not change, so it is not free in a resize or scroll handler. For container sizing, see Grid size.
Related articles
Related guides
Configuration options
Core methods
Hooks