Async values
Added in Handsontable 19.0.0Fill cells from promises — a remote lookup, a server-computed value, or an AI model — and show a pending and an error state in each cell while the request runs.
Overview
The AsyncValues plugin of Handsontable DataGrid starts a request per cell, or one request for a batch of cells. While a request is pending, the cell keeps its current value and shows a spinner. When the promise resolves, the plugin writes the value into the cell. When it rejects, the cell keeps its previous value, and shows an error state with the rejection message.
Each request gets an AbortSignal. The plugin aborts it, and ignores the request’s late result, when:
- The user or your code changes the cell’s value.
- The user or your code changes a cell the request depends on.
- A new request starts for the same cell.
- The row is removed, or replaced data no longer holds the row.
Requests are tied to the row’s physical index, so sorting, filtering, or moving rows on the client while a request is pending still writes the result to the right record. With row ids, requests also follow their rows when the data is replaced.
The plugin can’t be enabled together with the NestedRows plugin.
Enable async values
Set the asyncValues option to true, and start requests with the setAsyncValue() method.
In the example below, click Look up products to fetch each product’s name by its SKU. The lookup for X-999 fails, so its cell shows the error state. Change a SKU to look its product up again — the change cancels a pending lookup or clears the error, and the example starts a new lookup from its afterChange hook.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const products = { 'A-100': 'Desk lamp', 'B-200': 'Office chair', 'C-300': 'Standing desk', 'D-400': 'Monitor arm',};
// A stand-in for a server request: it answers after a delay, and stops when the signal is aborted.function lookUpProduct(sku, signal) { return new Promise((resolve, reject) => { const timer = setTimeout( () => { if (products[sku]) { resolve(products[sku]); } else { reject(new Error(`Unknown SKU: ${sku}`)); } }, 600 + Math.random() * 1400, );
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }); });}
const container = document.querySelector('#example1');const hot = new Handsontable(container, { data: [ { sku: 'A-100', product: '' }, { sku: 'B-200', product: '' }, { sku: 'X-999', product: '' }, { sku: 'C-300', product: '' }, { sku: 'D-400', product: '' }, ], columns: [ { data: 'sku', title: 'SKU' }, { data: 'product', title: 'Product', readOnly: true }, ], colWidths: [120, 220], rowHeaders: true, height: 'auto', asyncValues: true, // Look the product up again when its SKU changes. afterChange(changes) { changes?.forEach(([row, prop]) => { if (row !== null && prop === 'sku') { lookUpRows(row, row); } }); }, autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});
function lookUpRows(fromRow, toRow) { hot .getPlugin('asyncValues') .setAsyncValues( fromRow, 1, toRow, 1, ({ physicalRow, signal }) => lookUpProduct(hot.getSourceDataAtCell(physicalRow, 'sku'), signal), { dependsOn: ['sku'] }, );}
document.querySelector('#lookup').addEventListener('click', () => { lookUpRows(0, hot.countRows() - 1);});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const products: Record<string, string> = { 'A-100': 'Desk lamp', 'B-200': 'Office chair', 'C-300': 'Standing desk', 'D-400': 'Monitor arm',};
// A stand-in for a server request: it answers after a delay, and stops when the signal is aborted.function lookUpProduct(sku: string, signal: AbortSignal): Promise<string> { return new Promise((resolve, reject) => { const timer = setTimeout(() => { if (products[sku]) { resolve(products[sku]); } else { reject(new Error(`Unknown SKU: ${sku}`)); } }, 600 + Math.random() * 1400);
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }); });}
const container = document.querySelector<HTMLElement>('#example1')!;const hot = new Handsontable(container, { data: [ { sku: 'A-100', product: '' }, { sku: 'B-200', product: '' }, { sku: 'X-999', product: '' }, { sku: 'C-300', product: '' }, { sku: 'D-400', product: '' }, ], columns: [ { data: 'sku', title: 'SKU' }, { data: 'product', title: 'Product', readOnly: true }, ], colWidths: [120, 220], rowHeaders: true, height: 'auto', asyncValues: true, // Look the product up again when its SKU changes. afterChange(changes) { changes?.forEach(([row, prop]) => { if (row !== null && prop === 'sku') { lookUpRows(row, row); } }); }, autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});
function lookUpRows(fromRow: number, toRow: number) { hot.getPlugin('asyncValues').setAsyncValues(fromRow, 1, toRow, 1, ({ physicalRow, signal }) => ( lookUpProduct(hot.getSourceDataAtCell(physicalRow, 'sku') as string, signal) ), { dependsOn: ['sku'] });}
document.querySelector<HTMLButtonElement>('#lookup')!.addEventListener('click', () => { lookUpRows(0, hot.countRows() - 1);});<div class="example-controls-container"> <div class="controls"> <button id="lookup" class="button button--primary">Look up products</button> </div></div>
<div id="example1"></div>Start a request
Pass the cell’s visual coordinates and a function that returns a promise. The function receives the request’s signal, and the cell’s row, column, physicalRow, prop, and rowId:
const asyncValues = hot.getPlugin('asyncValues');
asyncValues.setAsyncValue(0, 2, async ({ physicalRow, signal }) => { const sku = hot.getSourceDataAtCell(physicalRow, 'sku'); const response = await fetch(`/api/products/${sku}`, { signal });
return (await response.json()).name;});Read the row’s data through physicalRow, as above. The visual index of a row can change before the promise settles, and a row that is filtered out has none (row is null).
You can also pass a promise instead of a function. A promise cannot receive the signal, so its work goes on after a cancellation, but the plugin still ignores its result. Only a function can be retried.
To start a request for every cell of a visual range, use setAsyncValues(). It calls the function once per cell, and renders the grid once.
Start requests by row id or physical row
A filtered-out or trimmed row has no visual index, so a visual range can’t reach it. Address such cells by physical row or by row id instead:
// one cellasyncValues.setAsyncValueAt({ rowId: 'SKU-4821', prop: 'name' }, source);asyncValues.setAsyncValueAt({ physicalRow: 12, prop: 'name' }, source);
// one column, for every row of the data, filtered-out rows includedasyncValues.setAsyncValuesForRows('all', 'name', source, { dependsOn: ['sku'] });
// one column, for some rowsasyncValues.setAsyncValuesForRows([{ rowId: 'SKU-4821' }, { rowId: 'SKU-0093' }], 'name', source);If a row or the column doesn’t exist, the method throws before it starts any request. cancelAt(), retryAt(), and getAsyncStateAt() take the same cell references.
Compute many cells in one request
An AI model or a bulk API is cheaper per batch than per cell. setAsyncValuesInBatches() calls your function once per batch of up to batchSize cells (default 25):
asyncValues.setAsyncValuesInBatches('all', 'category', async (cells, signal) => { const products = cells.map(({ physicalRow }) => hot.getSourceDataAtCell(physicalRow, 'product')); const response = await fetch('/api/classify', { method: 'POST', body: JSON.stringify(products), signal }); const answers = await response.json();
// One element per cell: a value, or an `Error` for a cell the model couldn't answer. return answers.map((answer) => (answer.ok ? answer.category : new Error(answer.reason)));}, { batchSize: 20, dependsOn: ['product'] });Each cell settles on its own: an Error element rejects only its cell, and a missing element (past the end of the array, a hole, or undefined) rejects it with an empty message. To clear a cell, answer null. A rejected batch rejects every cell of the batch, and so does an answer that isn’t an array (the plugin also logs a warning). The batch’s signal aborts only when every cell of the batch is canceled, so cancelling a few cells doesn’t stop the request for the others. A row listed twice is computed once, and both of its results settle with the same value.
Limit concurrent requests and coalesce writes
For hundreds of rows, set the plugin’s options:
asyncValues: { concurrency: 4, // at most four sources (or batches) run at once (default: 6) flush: 'frame', // write the results that arrived once per animation frame},With concurrency, the cells beyond the limit stay pending and wait for a free slot. The default of 6 matches the number of connections a browser opens to one server; set Infinity to start every source at once. A canceled cell gives its slot back at once, even when its request ignores the signal. A batch gives its slot back once every cell of the batch is canceled.
flush decides when settled requests are written:
flush | Writes |
|---|---|
'microtask' (default) | Right after the task the requests settled in. Responses that arrive separately, as network responses do, are written one by one. |
'frame' | Once per animation frame. |
| A number | After that many milliseconds, collecting every result that settled meanwhile. |
The grid renders at most once per animation frame: a flush renders at once, and a later flush in the same frame renders when the frame comes. So separate network responses don’t each render the grid. Each flush writes one change per write source: afterChange fires once for the rows the grid shows, and the rows hidden by a filter are written separately, without afterChange (see Validation).
Show progress, retry, and stop
countPending() and countErrors() give the numbers for a progress display. getPendingCells() and getErrorCells() list the cells as { physicalRow, prop, rowId } objects. The afterAsyncValuesIdle hook fires when the last pending request settles.
retryErrors() starts every failed cell again, with the source and the options it failed with. Cells that failed in one batch are retried in batches again. retry() does the same for one cell. Pass keepSource: false to a request to let a failed cell drop its source.
cancelAll() stops everything.
The example below classifies products with a stand-in model, in batches of four, two batches at a time. Click Classify, then Stop or Retry failed:
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const categories = [ ['bottle', 'Drinkware'], ['water', 'Drinkware'], ['mouse', 'Electronics'], ['usb', 'Electronics'], ['speaker', 'Electronics'], ['chair', 'Furniture'], ['desk', 'Furniture'], ['stand', 'Furniture'], ['bag', 'Apparel'],];
// A stand-in for a model call: it classifies a batch after a delay, and stops when the signal is aborted.function classifyProducts(products, signal) { return new Promise((resolve, reject) => { const timer = setTimeout( () => { resolve( products.map((product) => { if (product === 'Ceramic Mug Set') { return new Error('The model could not classify this product'); }
return categories.find(([keyword]) => product.toLowerCase().includes(keyword))?.[1] ?? 'Other'; }), ); }, 500 + Math.random() * 700, );
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }); });}
const container = document.querySelector('#example2');const output = document.querySelector('#progress');const hot = new Handsontable(container, { data: [ { id: 1, sku: 'SKU-4821', product: 'Stainless Steel Water Bottle', category: null }, { id: 2, sku: 'SKU-0093', product: 'Wireless Mouse', category: null }, { id: 3, sku: 'SKU-1170', product: 'Ergonomic Office Chair', category: null }, { id: 4, sku: 'SKU-2208', product: 'USB-C Charging Cable', category: null }, { id: 5, sku: 'SKU-3341', product: 'Aluminum Water Filter', category: null }, { id: 6, sku: 'SKU-4412', product: 'Canvas Tote Bag', category: null }, { id: 7, sku: 'SKU-5088', product: 'USB-C Hub', category: null }, { id: 8, sku: 'SKU-6120', product: 'Ceramic Mug Set', category: null }, { id: 9, sku: 'SKU-7294', product: 'Desk Lamp', category: null }, { id: 10, sku: 'SKU-8015', product: 'Laptop Stand', category: null }, { id: 11, sku: 'SKU-9166', product: 'Bluetooth Speaker', category: null }, { id: 12, sku: 'SKU-1042', product: 'Standing Desk', category: null }, ], columns: [ { data: 'sku', title: 'SKU' }, { data: 'product', title: 'Product' }, { data: 'category', title: 'Category', readOnly: true }, ], colWidths: [110, 230, 130], rowId: 'id', asyncValues: { concurrency: 2 }, rowHeaders: true, height: 'auto', autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});const plugin = hot.getPlugin('asyncValues');
// Show how many cells are done and how many failed.const updateProgress = () => { const done = hot.getSourceDataAtCol(2).filter((category) => category !== null).length;
output.textContent = `${done} of ${hot.countRows()} done, ${plugin.countErrors()} failed`;};
hot.addHook('afterAsyncValueStart', updateProgress);hot.addHook('afterAsyncValueResolve', updateProgress);hot.addHook('afterAsyncValueReject', updateProgress);hot.addHook('afterAsyncValueCancel', updateProgress);hot.addHook('afterAsyncValuesIdle', updateProgress);
document.querySelector('#classify').addEventListener('click', () => { plugin.setAsyncValuesInBatches( 'all', 'category', (cells, signal) => classifyProducts( cells.map((cell) => hot.getSourceDataAtCell(cell.physicalRow, 'product')), signal, ), { batchSize: 4, dependsOn: ['product'], source: 'AI.classify', meta: { aiGenerated: true } }, );});document.querySelector('#retry').addEventListener('click', () => plugin.retryErrors());document.querySelector('#stop').addEventListener('click', () => plugin.cancelAll());updateProgress();import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const categories: [string, string][] = [ ['bottle', 'Drinkware'], ['water', 'Drinkware'], ['mouse', 'Electronics'], ['usb', 'Electronics'], ['speaker', 'Electronics'], ['chair', 'Furniture'], ['desk', 'Furniture'], ['stand', 'Furniture'], ['bag', 'Apparel'],];
// A stand-in for a model call: it classifies a batch after a delay, and stops when the signal is aborted.function classifyProducts(products: string[], signal: AbortSignal): Promise<(string | Error)[]> { return new Promise((resolve, reject) => { const timer = setTimeout(() => { resolve(products.map((product) => { if (product === 'Ceramic Mug Set') { return new Error('The model could not classify this product'); }
return categories.find(([keyword]) => product.toLowerCase().includes(keyword))?.[1] ?? 'Other'; })); }, 500 + Math.random() * 700);
signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }); });}
const container = document.querySelector<HTMLElement>('#example2')!;const output = document.querySelector<HTMLElement>('#progress')!;const hot = new Handsontable(container, { data: [ { id: 1, sku: 'SKU-4821', product: 'Stainless Steel Water Bottle', category: null }, { id: 2, sku: 'SKU-0093', product: 'Wireless Mouse', category: null }, { id: 3, sku: 'SKU-1170', product: 'Ergonomic Office Chair', category: null }, { id: 4, sku: 'SKU-2208', product: 'USB-C Charging Cable', category: null }, { id: 5, sku: 'SKU-3341', product: 'Aluminum Water Filter', category: null }, { id: 6, sku: 'SKU-4412', product: 'Canvas Tote Bag', category: null }, { id: 7, sku: 'SKU-5088', product: 'USB-C Hub', category: null }, { id: 8, sku: 'SKU-6120', product: 'Ceramic Mug Set', category: null }, { id: 9, sku: 'SKU-7294', product: 'Desk Lamp', category: null }, { id: 10, sku: 'SKU-8015', product: 'Laptop Stand', category: null }, { id: 11, sku: 'SKU-9166', product: 'Bluetooth Speaker', category: null }, { id: 12, sku: 'SKU-1042', product: 'Standing Desk', category: null }, ], columns: [ { data: 'sku', title: 'SKU' }, { data: 'product', title: 'Product' }, { data: 'category', title: 'Category', readOnly: true }, ], colWidths: [110, 230, 130], rowId: 'id', asyncValues: { concurrency: 2 }, rowHeaders: true, height: 'auto', autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});const plugin = hot.getPlugin('asyncValues');
// Show how many cells are done and how many failed.const updateProgress = () => { const done = hot.getSourceDataAtCol(2).filter(category => category !== null).length;
output.textContent = `${done} of ${hot.countRows()} done, ${plugin.countErrors()} failed`;};
hot.addHook('afterAsyncValueStart', updateProgress);hot.addHook('afterAsyncValueResolve', updateProgress);hot.addHook('afterAsyncValueReject', updateProgress);hot.addHook('afterAsyncValueCancel', updateProgress);hot.addHook('afterAsyncValuesIdle', updateProgress);
document.querySelector<HTMLButtonElement>('#classify')!.addEventListener('click', () => { plugin.setAsyncValuesInBatches('all', 'category', (cells, signal) => ( classifyProducts(cells.map(cell => hot.getSourceDataAtCell(cell.physicalRow, 'product') as string), signal) ), { batchSize: 4, dependsOn: ['product'], source: 'AI.classify', meta: { aiGenerated: true } });});document.querySelector<HTMLButtonElement>('#retry')!.addEventListener('click', () => plugin.retryErrors());document.querySelector<HTMLButtonElement>('#stop')!.addEventListener('click', () => plugin.cancelAll());updateProgress();<div class="example-controls-container"> <div class="controls"> <button id="classify" class="button button--primary">Classify</button> <button id="retry" class="button button--primary">Retry failed</button> <button id="stop" class="button button--primary">Stop</button> <span id="progress"></span> </div></div>
<div id="example2"></div>Cancel a request when its inputs change
List the columns a value is computed from in the dependsOn option. A change to any of them, in the same row, cancels the request, or clears the error state a failed request left:
asyncValues.setAsyncValue(row, 2, source, { dependsOn: ['sku', 'quantity'] });dependsOn takes column properties: the data keys of object data, or the physical column indexes of array data. A resolved value is a change too, so it cancels the pending requests that depend on its cell, and a value computed from an input that lands in the same write is canceled as well.
A value that arrives while the user edits its cell is dropped: the request ends canceled with the 'edit' reason, and the user’s text stays in the editor.
The plugin does not start a new request on its own. Start one from your afterChange hook when an input column changes, as the first example does. The plugin handles afterChange before the listeners you add to the grid, so the change cancels the old request first, and your new request stays. A global listener (Handsontable.hooks.add() without an instance) runs before every instance listener, so it can’t start the new request this way.
To cancel requests from your code, use cancel() for one cell, or cancelAll() for every cell. Both also clear the error state.
Request options
Every method that starts requests takes these options:
| Option | Default | Description |
|---|---|---|
dependsOn | [] | The columns, in the same row, whose change cancels the request. |
source | 'AsyncValues.resolve' | The source the value is written with, as beforeChange and afterChange receive it. Use your own (for example, 'AI.classify') to tell AI writes apart in your hooks, in a backend sync, or in an audit log. 'auto', 'UndoRedo.undo', 'UndoRedo.redo', and a source ending with Validator are reserved: the plugin logs a warning and uses the default. |
meta | none | Cell meta merged into the cell once the grid stores its value, for example { aiGenerated: true }. A value that beforeChange or a validator rejects gets no meta. Applied to rows with a visual index only. Never part of an undo step, so an undo doesn’t remove it. |
undo | 'skip' | 'skip' writes the values without an undo step. 'record' records every value the call wrote as one undo step (see Undo). |
keepSource | true | Whether a failed cell keeps its source for retry(). |
batchSize | 25 | The cells per call of a batch source (setAsyncValuesInBatches() only). |
Review values before they’re written
The beforeAsyncValueStart hook can skip a request: return false, and the cell doesn’t become pending and its source isn’t called. Use it to throttle or to skip rows that already have a value. A skipped request’s promise resolves as canceled with the 'vetoed' reason, but no afterAsyncValueCancel hook fires, because nothing was pending.
The beforeAsyncValueResolve hook receives each resolved value before it’s written. Return another value to write that one instead, or false to discard it (the cell keeps its previous value):
const hot = new Handsontable(container, { // ... asyncValues: true, beforeAsyncValueResolve(value, physicalRow, prop, rowId) { if (!allowedCategories.includes(value)) { return false; // discard a suggestion outside the list }
return value.trim(); },});A discarded value ends its request as canceled, with the 'vetoed' reason, and fires afterAsyncValueCancel. Because false discards, a listener can’t replace a value with a literal false.
When several listeners are added to one of these hooks, each one receives the previous listener’s result as its first argument, unless that result is undefined. So:
- Return
undefined(or nothing) to keep a request or a value. ReturningtruefrombeforeAsyncValueStartpassestrueto the next listener in place of the row index. - To respect an earlier listener’s decision, check whether the first argument is
false.
Every beforeAsyncValueResolve listener of a flush runs before any value is written. A listener that throws fails its own cell with the error it threw. The plugin writes the other cells, then reports the error as an uncaught error.
A beforeAsyncValueStart listener that throws skips its cell. The method that started the requests starts the other cells first, then throws the error.
A listener of any other async values hook that throws doesn’t keep the other cells from their hooks.
Read the state of a cell
getAsyncState() returns { status: 'pending' }, { status: 'error', error, message }, or null. isPending() returns a boolean. getAsyncStateAt() and isPendingAt() take a cell by physical row or row id.
The state is also available in the cell meta, so a custom renderer can read it:
| Cell meta key | Value |
|---|---|
asyncState | 'pending', 'error', or null (undefined on a cell that never had a request) |
asyncError | The error message, or null |
The error message is the rejection reason’s message, or the reason converted to a string.
Every method that starts requests returns a promise that never rejects. It resolves with an object (or an array of them) that tells how each request ended: { status: 'resolved', value }, { status: 'rejected', error, message }, or { status: 'canceled', reason }.
resolved means the plugin passed the value to the grid. A beforeChange listener, or a validator with allowInvalid: false, can still change or reject the value, and a later write to the cell can drop it (see Undo). A cell with a validator gets the value after the validation finishes, so read it in afterChange rather than right after the promise resolves.
Hooks
| Hook | Fires |
|---|---|
beforeAsyncValueStart | Before a request starts. Return false to skip it. |
afterAsyncValueStart | After a request starts. |
beforeAsyncValueResolve | Before a resolved value is written. Return a value to replace it, or false to discard it. |
afterAsyncValueResolve | After a resolved value is passed to the grid. |
afterAsyncValueReject | After a request rejects. |
afterAsyncValueCancel | After a pending request is canceled. |
afterAsyncValuesIdle | After the last pending request settles. |
Each hook (except afterAsyncValuesIdle) receives the cell’s physical row index, its column property, and its row id (null without row ids). A row hidden by a filter has no visual index, which is why the hooks use physical coordinates. To get the visual row, call toVisualRow().
afterAsyncValueCancel also receives the reason: 'edit', 'dependency', 'restart', 'rowRemoved', 'columnsChanged', 'dataReplaced', 'manual', 'disabled', or 'vetoed'. For exhaustive handling, the ASYNC_VALUE_CANCEL_REASONS array lists them all. Import it from the plugin’s module (an ES module):
import { ASYNC_VALUE_CANCEL_REASONS } from 'handsontable/plugins/asyncValues';When a row is removed or replaced (the 'rowRemoved' and 'dataReplaced' reasons), rowId is the id the row held, not the id of the row that now sits at its index. Without row ids it is null.
When you remove several non-contiguous groups of rows, the grid removes the groups one at a time. physicalRow is then the row’s index just before its own group is removed. Key your handling on rowId.
Undo
By default (undo: 'skip'), a resolved value is not added to the undo history. Undo of an earlier edit of the same cell restores the value that edit replaced, over the async value.
With undo: 'record', every value one call wrote becomes one undo step, recorded when the call’s last request settles:
asyncValues.setAsyncValuesInBatches('all', 'category', classify, { undo: 'record' });One undo then reverts the whole run, and one redo applies it again. The values appear while the run is in progress, so the user can keep editing and undoing meanwhile. The step lands on the undo stack once the run’s last request settles and its last value passes the cell’s validator. For a cell without a validator, the step is there by the time the call’s promise resolves. A validator can answer later than that, and the step then lands when the last validator answers.
The step is a 'change' action with the call’s source, as beforeUndo receives it. It records what the grid stored, after a valueSetter or a validator changed the value, a validator that corrects the value through a source ending with Validator included. When two calls write one cell while its validator runs, the cell keeps the value of the write made last, and that value is what the later call’s step records. Like any new step, it clears the redo history: an undo the user makes while a run is in progress can’t be redone once the run’s step lands.
A few values stay out of the run’s step:
- A cell the user edits after its value landed: the user’s edit is a step of its own.
- A cell that a later call writes before this call finishes: the later call’s step owns it.
- A value the grid dropped because it applied a later write to the same cell instead.
- A cell that a data update, such as
updateData(), changed after the value landed. - The
metathe run merged into the cells: an undo doesn’t remove it.
If you disable the plugin while a call is in progress, the call’s step records the values that already landed.
A cell’s validator decides when a value lands. When two writes reach one cell and both wait on a validator, the grid applies the write made last, whatever order the validators answer in. A write that skips the validator is not ordered, and neither is a cell without a validator that a call writes together with a validated cell (see Cell validator). So if the user edits a cell while the async value written to it still waits for its validator, and the edit’s validator answers first, the user’s edit stays and the grid drops the async value. If the async value’s validator answers first, the value lands and the edit then replaces it. If a validator with allowInvalid: false rejects the edit, the async value still lands.
A dropped async value still ends as { status: 'resolved', value }, because the plugin passed it to the grid. This differs from an edit made while the request is pending, or while the cell’s editor is open: that edit cancels the request with the 'edit' reason. A dropped value is the case where the edit is committed after the request resolved, while the value waits for its validator. No cancel hook fires for it. The dropped value fires beforeChange, but not afterChange (see Cell validator). To tell that a value landed, listen to afterChange for the request’s source. A row hidden by a filter fires no afterChange (see Validation).
An undo or redo that changes a pending cell cancels its request, and redo does not start it again.
Framework apps and data updates
The React wrapper calls updateData() whenever it receives a data prop, which is on every render, and the Angular wrapper calls it whenever data changes. Pending requests survive those updates:
- With row ids (the
rowIdoption, ordataProvider.rowId), each request moves to the row that holds the same id in the new data. A request whose row id is gone is canceled with the'rowRemoved'reason. - Without row ids,
updateData()moves each request with its row object when the new array holds the same objects. With copies, it keeps each request on the same physical row, the way it keeps cell meta. If your app passes reordered copies, setrowId, or the results land on whatever record moved into that position.
loadData() starts a new dataset: with row ids, requests follow their ids as above; without them, every request is canceled with the 'dataReplaced' reason.
The Vue wrapper keeps your data array by reference. When the array gains or loses rows, the wrapper only resizes the grid’s row index, at its end. With row ids, each pending request then moves to the row that holds its id; a request whose row is gone is canceled with the 'rowRemoved' reason. Without row ids, requests keep their physical rows, so insert rows at the end of the array, or set rowId.
If your app stores resolved values in its own state, read them in afterChange, which fires only for a value that landed. For rows hidden by a filter, use afterAsyncValueResolve, which fires when the plugin passes the value to the grid. Then pass the updated data back as usual. The other pending requests keep running.
Save resolved values to a server
With the DataProvider plugin, a resolved value is not sent to onRowsUpdate by default, so the next refetch replaces it. To save resolved values, set saveToDataProvider to true in the plugin’s options:
const hot = new Handsontable(container, { asyncValues: { saveToDataProvider: true }, dataProvider: { rowId: 'id', fetchRows: (query) => fetchProducts(query), onRowsCreate: (rows) => createProducts(rows), onRowsUpdate: (rows) => updateProducts(rows), onRowsRemove: (ids) => removeProducts(ids), },});The plugin sends the values of one flush in one updateRows() call. It needs dataProvider.rowId and onRowsUpdate, and it warns once when either is missing. The save follows these rules:
- A value is saved only when the grid stored it. A value that
beforeChangeor a validator rejected, a value a validator marked invalid (withallowInvalid), a rejected request, and a cell the user edited after the value landed are not saved. A value a validator corrects before the save is saved corrected. - A failed save leaves the cell resolved. Handle it in
afterRowsMutationError. - The values of a call with
undo: 'record'are not saved. - Each save is a serialized
onRowsUpdatecall followed by a refetch. The refetch loads the data again, so it clears the undo and redo stack. Values that resolve in separate tasks make separate calls, and a value that resolves while a save runs waits for it. Use a numericflushto merge responses into fewer calls. - A save that runs while a page change is loading refetches the old page, because the new page is not stored until its fetch ends.
- A correction a validator makes after the save went out is not saved again.
- A call with a
sourcethat DataProvider already saves, such as'edit', is saved twice.
How async values work with other features
- Validation: a resolved value goes through
beforeChange, the cell’s validator, andafterChange, with the request’ssource. A later write to the cell can drop the value beforeafterChange(see Undo). A row hidden by a filter, or pastmaxRows, has no visual index, so its value is written withsetSourceDataAtCell(): the cell’s validator does not run, asourceDataValidatordoes, andafterChangedoes not fire. - Many calls: each call that starts or cancels requests renders the grid once. To start many cells, call
setAsyncValuesForRows()orsetAsyncValues()once, or wrap your loop inbatch(). - Copy, paste, and export: copy and export read the cell’s current value — its previous value while a request is pending or failed. With
copyPendingAs: 'empty'in the plugin’s options, copying or cutting puts an empty value for a pending cell. The empty value also applies to the data a paste into another Handsontable grid reads, including withparsePastedValue. A paste into a pending cell is an edit, so it cancels the request. - Rows and columns: inserting rows keeps every request on its record. Removing a row cancels its requests. In array data, whose column properties are indexes, inserting or removing a column cancels the requests of that column and the columns after it.
- Server-side data: with the
DataProviderplugin, a refetch (a sort, a filter, a page change, or the refetch after a saved edit) loads new data. WithdataProvider.rowId, the requests of the rows still on the page keep running; the others are canceled. To save resolved values, see Save resolved values to a server. - Settings:
updateSettings()keeps pending requests, even when it sendsasyncValuesagain, as the framework wrappers do, and when it changescolumns. A raisedconcurrencystarts the waiting requests that now fit. SettingasyncValuestofalseor enablingnestedRowscancels every request. - Nested rows: the plugin can’t be enabled together with the
NestedRowsplugin, which moves rows without keeping their physical indexes.
Styling
The plugin adds these classes to a cell:
| Class | Cell state |
|---|---|
htAsyncPending | A request is pending. The spinner is a span.htAsyncIndicator element inside the cell. |
htAsyncError | The last request failed. The cell gets a background color and a bar at its inline start (span.htAsyncErrorMarker), so the state doesn’t rely on color alone. |
Three theme variables control the colors, so an async error can look different from a validation error:
| CSS variable | Default |
|---|---|
--ht-async-indicator-color | --ht-accent-color |
--ht-async-error-background-color | --ht-cell-error-background-color |
--ht-async-error-marker-color | --ht-notification-error-accent |
With prefers-reduced-motion: reduce, the spinner does not spin. The spinner sits at the inline end of the cell, next to a dropdown arrow, and on the left in a right-aligned cell (a numeric one, for example), so it doesn’t cover the value’s end. It can still cover the end of a long value.
Accessibility
A pending cell has aria-busy="true" and visually hidden “Loading…” text (span.htAsyncPendingMessage, translated with the grid’s language), because screen readers don’t announce aria-busy on a cell. A failed cell has aria-invalid="true", and carries the error message twice: in its title attribute, which a pointer shows on hover, and in visually hidden text (span.htAsyncErrorMessage), which a screen reader reads with the cell. When the request of the selected cell fails, the error message is also announced. Both ARIA attributes, and the announcement, follow the ariaTags option.
Related API reference
- Configuration options:
- Plugins:
- Hooks: