Run Handsontable in a Salesforce Lightning Web Component

In this tutorial, you will run Handsontable inside a Salesforce Lightning Web Component, bound to live Account records. It covers only the glue between the grid and the platform: shipping the library as a static resource, getting its stylesheets across the shadow boundary, mapping Salesforce field metadata to column types, and turning grid hooks into Lightning Data Service calls. It assumes you already write Lightning Web Components.

Overview

Get the full source on GitHub

Handsontable running as a Lightning Web Component on a Salesforce Lightning app page, showing Account records with grouped columns

Difficulty: Intermediate
Time: ~30 minutes

Handsontable resolves mouse, focus, and clipboard events across the shadow boundary on its own, so clicking, the cell editors, copy and paste, and the context menu work under Lightning Web Security with no workaround code. The rest is the four points of contact this recipe wires up.

This recipe runs against real org data, so the grid cannot run inside this page. The code below is complete, but it arrives in pieces: each step adds members to a class you already started. The repository holds both components as whole files if you would rather read them that way, or deploy them and follow along.

What you’ll build

A Lightning app page with an editable grid of Account records:

Handsontable loaded from a static resource, with no bundler and no npm dependency in the org.
Column types derived from Salesforce field metadata: picklists become dropdowns, numeric fields become numeric cells, and checkboxes become boolean cells.
Grouped, collapsible column headers built from field name prefixes such as Billing and Shipping.
Cell edits, new rows, and deleted rows saved to Salesforce through Lightning Data Service, with no Apex.

Two components: hotGrid loads the static resource, creates the instance, and re-exposes settings as @api properties and hooks as DOM events; handsontableApp reads Account metadata and records, builds the column configuration, and writes changes back. The wrapper carries no Account-specific code, so it works for any object.

Before you begin

You need the Salesforce CLI (sf) and an org you can deploy to - Developer Edition, a sandbox, or a Starter trial.

See the Shadow DOM guide for what the grid handles at the boundary.

You also need Account records in the All Accounts list view. Developer Edition orgs ship with sample accounts.

Authorize your org, and keep the alias - every command below targets it:

1
sf org login web --alias my-org --set-default

If you are starting from an empty directory, scaffold a project first:

1
sf project generate --name handsontable-lwc
2
cd handsontable-lwc

Add Handsontable as a static resource

Vendor three files from the package into a static resource and commit them:
Terminal window
```
1
npm install handsontable
2
mkdir -p force-app/main/default/staticresources/handsontable
3
cp node_modules/handsontable/dist/handsontable.full.min.js \
4
   node_modules/handsontable/styles/handsontable.min.css \
5
   node_modules/handsontable/styles/ht-theme-main.min.css \
6
   force-app/main/default/staticresources/handsontable/
```
That leaves the resource directory next to its metadata file:
```
1
force-app/main/default/staticresources/
2
├── handsontable/
3
│   ├── handsontable.full.min.js
4
│   ├── handsontable.min.css
5
│   └── ht-theme-main.min.css
6
└── handsontable.resource-meta.xml
```
The npm dependency records which version you vendored; to upgrade, bump the package and repeat the copy. Without node in the project, download the same three files from a version-pinned CDN: the script, the base stylesheet, and the theme stylesheet. Keep the version in the URL - a static resource is a snapshot, so an unpinned URL changes what you uploaded.

One archive resource keeps the three files on one version, and ${HANDSONTABLE}/<file> then addresses them. Three single-file resources work too, each with its own contentType and resourceUrl import.

Create handsontable.resource-meta.xml beside the directory:
```
1
<?xml version="1.0" encoding="UTF-8"?>
2
<StaticResource xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <cacheControl>Public</cacheControl>
4
    <contentType>application/zip</contentType>
5
    <description>Handsontable - JavaScript data grid with spreadsheet UX. Includes JS, CSS, and theme files.</description>
6
</StaticResource>
```
contentType is application/zip because the CLI zips the directory on deploy; a Metadata API deploy needs the archive built yourself.

Load both stylesheets in the next step. handsontable.min.css carries the grid’s structural styles, and ht-theme-main.min.css carries one theme. Without the structural stylesheet, cell editors open in the wrong position.

Create the grid wrapper component

Generate the component:

1
sf lightning generate component --type lwc --name hotGrid --output-dir force-app/main/default/lwc

Handsontable writes its own DOM, so its container needs lwc:dom="manual". The theme class goes on the same element:

1
<template>
2
    <div class="grid-container ht-theme-main" lwc:dom="manual"></div>
3
</template>

Load the resource in renderedCallback, guarded by a flag. Order matters: both stylesheets, then the script, then the grid:

1
import { LightningElement, api } from 'lwc';
2
import { loadScript, loadStyle } from 'lightning/platformResourceLoader';
3
import HANDSONTABLE from '@salesforce/resourceUrl/handsontable';
4

5
export default class HotGrid extends LightningElement {
6
    _hot = null;
7
    _initialized = false;
8
    _data = [];
9
    _columns = [];
10
    _nestedHeaders = [];
11
    _collapsibleColumns = [];
12

13
    renderedCallback() {
14
        if (this._initialized) {
15
            return;
16
        }
17
        this._initialized = true;
18

19
        loadStyle(this, `${HANDSONTABLE}/handsontable.min.css`)
20
            .then(() => loadStyle(this, `${HANDSONTABLE}/ht-theme-main.min.css`))
21
            .then(() => loadScript(this, `${HANDSONTABLE}/handsontable.full.min.js`))
22
            .then(() => {
23
                const container = this.template.querySelector('.grid-container');
24

25
                if (container) {
26
                    this._initializeGrid(container);
27
                }
28
            })
29
            .catch((error) => {
30
                console.error('HotGrid: failed to load', error?.message || error);
31
            });
32
    }
33

34
    disconnectedCallback() {
35
        if (this._hot) {
36
            this._hot.destroy();
37
            this._hot = null;
38
        }
39
    }
40

41
    _initializeGrid(container) {
42
        if (this._hot) {
43
            return;
44
        }
45

46
        const settings = {
47
            data: JSON.parse(JSON.stringify(this._data)),
48
            columns: this._columns.length ? this._columns : undefined,
49
            colHeaders: true,
50
            rowHeaders: true,
51
            height: 'auto',
52
            columnSorting: true,
53
            manualColumnResize: true,
54
            contextMenu: true,
55
            copyPaste: true,
56
            fillHandle: true,
57
            licenseKey: 'non-commercial-and-evaluation',
58
            afterChange: (changes, source) => {
59
                if (!changes || source === 'loadData') {
60
                    return;
61
                }
62

63
                changes.forEach(([row, col, oldValue, newValue]) => {
64
                    if (oldValue !== newValue) {
65
                        this.dispatchEvent(new CustomEvent('cellchange', {
66
                            detail: {
67
                                row,
68
                                physicalRow: this._hot.toPhysicalRow(row),
69
                                col,
70
                                oldValue,
71
                                newValue,
72
                            },
73
                        }));
74
                    }
75
                });
76
            },
77
            afterCreateRow: (index, amount) => {
78
                this.dispatchEvent(new CustomEvent('rowcreate', {
79
                    detail: { index, physicalIndex: this._hot.toPhysicalRow(index), amount },
80
                }));
81
            },
82
            beforeRemoveRow: (index, amount, physicalRows) => {
83
                this.dispatchEvent(new CustomEvent('rowremoverequest', {
84
                    detail: { physicalRows: [...physicalRows] },
85
                }));
86

87
                return false;
88
            },
89
        };
90

91
        if (this._nestedHeaders.length) {
92
            settings.nestedHeaders = this._nestedHeaders;
93
            settings.collapsibleColumns = this._collapsibleColumns.length
94
                ? this._collapsibleColumns : true;
95
        }
96

97
        this._hot = new window.Handsontable(container, settings);
98
    }
99
}

Three details:

loadScript attaches the library to window.Handsontable, so the instance comes from the global, not from an import.
destroy() in disconnectedCallback is not optional. Lightning Experience keeps navigated-away pages in memory, and an undestroyed grid keeps its listeners and its resize observer.
The events carry physical row indexes. The hooks report visual indexes, which move when the user sorts a column, while the data component’s arrays keep source order - an event carrying only the visual index would resolve a different record after a sort. toPhysicalRow() translates the first two, and beforeRemoveRow already receives its physical indexes as the third argument. See Understanding data and indexes.

Replace licenseKey with your commercial key before production. See License key.

Keep the wrapper unexposed:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <isExposed>false</isExposed>
4
    <description>Core Handsontable wrapper component for LWC. Not intended for direct use on Lightning pages.</description>
5
</LightningComponentBundle>

Understand which shadow DOM mode you are in

Lightning Experience renders components with a synthetic shadow DOM polyfill by default, and this recipe sets no shadowSupportMode, so the grid runs in that mode. Step 2 is complete as written for it: loadStyle puts a <link> in document.head, and synthetic shadow DOM lets those styles reach the component.

To check which mode an org actually gives you, open the page with the grid on it, and run this in the browser console:

1
const probe = document.createElement('style');
2

3
probe.textContent = '.ht_master td { color: rgb(255, 0, 0) !important; }';
4
document.head.appendChild(probe);

Red cell text means the styles are not encapsulated, so the component runs in synthetic shadow DOM. Unchanged text means a native shadow root.

Handsontable adds the ht-shadow-dom class to its root wrapper in both modes. The class carries isolation: isolate, which keeps the grid’s overlays from competing with the Lightning Experience UI - but the declaration lives in handsontable.min.css, so the isolation only takes effect where that stylesheet reaches the grid. An unstyled grid has the class and none of the behavior.

Use native shadow DOM

A native shadow root ignores document.head, so with static shadowSupportMode = 'native' the grid renders unstyled: no cell borders, transparent backgrounds, and the browser’s default font. Load the stylesheets twice - once inside the shadow root for the grid, and once in the document head for the parts Handsontable renders outside it. Only the parts that change are shown here; the rest of the class stays as it is in Step 2:

1
// force-app/main/default/lwc/hotGrid/hotGrid.js - changed parts only
2
export default class HotGrid extends LightningElement {
3
    static shadowSupportMode = 'native';
4

5
    renderedCallback() {
6
        if (this._initialized) {
7
            return;
8
        }
9
        this._initialized = true;
10

11
        const loadStylesheetInShadow = (href) => new Promise((resolve, reject) => {
12
            const link = document.createElement('link');
13

14
            link.rel = 'stylesheet';
15
            link.href = href;
16
            link.onload = resolve;
17
            link.onerror = () => reject(new Error(`Failed to load ${href}`));
18

19
            this.template.querySelector('.grid-container').appendChild(link);
20
        });
21

22
        Promise.all([
23
            loadStylesheetInShadow(`${HANDSONTABLE}/handsontable.min.css`),
24
            loadStylesheetInShadow(`${HANDSONTABLE}/ht-theme-main.min.css`),
25
            loadStyle(this, `${HANDSONTABLE}/handsontable.min.css`),
26
            loadStyle(this, `${HANDSONTABLE}/ht-theme-main.min.css`),
27
        ])
28
            .then(() => loadScript(this, `${HANDSONTABLE}/handsontable.full.min.js`))
29
            .then(() => {
30
                const container = this.template.querySelector('.grid-container');
31

32
                if (container) {
33
                    this._initializeGrid(container);
34
                }
35
            })
36
            .catch((error) => {
37
                console.error('HotGrid: failed to load', error?.message || error);
38
            });
39
    }
40
}

The shadow-root copies style the grid. The head copies style the context menu and the other dropdowns, which Handsontable renders into a portal in the document, outside the shadow root - drop them and the menu opens transparent, borderless, and without a shadow. The Shadow DOM guide shows the same split for a plain web component.

Lightning Experience caches component bundles per session, so after you redeploy the wrapper, check the styles in a private window. A hard refresh, and even a new tab, can still run the previous version.

Expose the grid’s settings and hooks

Each setting is an @api accessor that also calls updateSettings() once the grid exists, so a wire that resolves after the first render still reaches it. Add these inside HotGrid:
```
1
// force-app/main/default/lwc/hotGrid/hotGrid.js - inside the class
2
@api
3
get data() {
4
    return this._data;
5
}
6
set data(value) {
7
    this._data = value ? [...value] : [];
8

9
    if (this._hot) {
10
        this._hot.updateSettings({ data: JSON.parse(JSON.stringify(this._data)) });
11
    }
12
}
13

14
@api
15
get columns() {
16
    return this._columns;
17
}
18
set columns(value) {
19
    this._columns = value ? [...value] : [];
20

21
    if (this._hot) {
22
        this._hot.updateSettings({ columns: this._columns.length ? this._columns : undefined });
23
    }
24
}
25

26
@api
27
get nestedHeaders() {
28
    return this._nestedHeaders;
29
}
30
set nestedHeaders(value) {
31
    this._nestedHeaders = value ? [...value] : [];
32

33
    if (this._hot && this._nestedHeaders.length) {
34
        this._hot.updateSettings({ nestedHeaders: this._nestedHeaders });
35
    }
36
}
37

38
@api
39
get collapsibleColumns() {
40
    return this._collapsibleColumns;
41
}
42
set collapsibleColumns(value) {
43
    this._collapsibleColumns = value ? [...value] : [];
44

45
    if (this._hot && this._collapsibleColumns.length) {
46
        this._hot.updateSettings({ collapsibleColumns: this._collapsibleColumns });
47
    }
48
}
49

50
@api
51
getDataAtCell(row, col) {
52
    return this._hot ? this._hot.getDataAtCell(row, col) : null;
53
}
```
_nestedHeaders and _collapsibleColumns are already declared in Step 2, and _initializeGrid() already reads them - grouped headers replace colHeaders when the data component supplies them.

Every setting the data component binds needs an accessor here, and a missing one fails silently: with nestedHeaders never set, the grid falls back to colHeaders: true and labels the columns A, B, C instead of the field names.

The copies are load-bearing. Handsontable mutates the data source it is given, and a parent’s reactive state arrives as a read-only proxy, so the deep copy and the array spreads are what keep the grid from writing into it. Skip them and the grid renders, every edit is rejected, the cell snaps back, and no afterChange fires.

The three hooks in that same settings object turn grid activity into DOM events. afterChange skips the loadData source, because without that guard the first data load reports every cell as an edit and the org receives a write for each one.

The two row hooks have opposite shapes on purpose. afterCreateRow reports a row the grid has already added, and that row stays local until the data component turns it into a record. beforeRemoveRow returns false, which cancels the removal: the data component owns data, so it decides when the row disappears and can put it back when the org refuses the delete.

Build the columns from Salesforce field metadata

Generate the data component:

1
sf lightning generate component --type lwc --name handsontableApp --output-dir force-app/main/default/lwc

Its template wires the grid’s properties and events:

1
<template>
2
    <template if:true={error}>
3
        <div class="slds-text-color_error slds-p-around_small">{error}</div>
4
    </template>
5
    <c-hot-grid
6
        data={data}
7
        columns={columns}
8
        nested-headers={nestedHeaders}
9
        collapsible-columns={collapsibleColumns}
10
        oncellchange={handleCellChange}
11
        onrowcreate={handleRowCreate}
12
        onrowremoverequest={handleRowRemoveRequest}>
13
    </c-hot-grid>
14
</template>

Four wire adapters feed the grid: getObjectInfo for data types and labels, getListInfoByName for the list view’s columns, getListRecordsByName for the records, and getPicklistValuesByRecordType for dropdown sources. The last one is easy to miss - getObjectInfo reports that a field is a picklist but never lists its values, so a dropdown built from it offers nothing to choose.

The two list adapters chain: getListRecordsByName takes a fields argument of qualified field names, which getListInfoByName supplies through its displayColumns. The records do not wait for it - while '$_listFields' is still undefined, the adapter emits the records once with empty field maps, then again with the field data once the names arrive. The builder skips the fieldless emission, and the other adapters resolve independently, so each wire calls the same builder and the builder waits for everything it reads.

Two traps in this pair, both verified against a live org. The adapters take objectApiName as a plain string: unlike getObjectInfo, they do not accept the @salesforce/schema object, and handed one they never provision - no request, no data, no error, and the grid renders empty with nothing in the console. And older examples use getListUi from lightning/uiListApi for the same job - Salesforce has deprecated it, and these two adapters are its replacement.

1
import { LightningElement, wire } from 'lwc';
2
import { getListInfoByName, getListRecordsByName } from 'lightning/uiListsApi';
3
import { getObjectInfo, getPicklistValuesByRecordType } from 'lightning/uiObjectInfoApi';
4
import { updateRecord, createRecord, deleteRecord } from 'lightning/uiRecordApi';
5
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
6

7
const SKIP_FIELDS = ['Id', 'OwnerId', 'Owner', 'CreatedById', 'LastModifiedById',
8
    'LastModifiedDate', 'CreatedDate', 'SystemModstamp', 'IsDeleted',
9
    'LastViewedDate', 'LastReferencedDate', 'MasterRecordId',
10
    'PhotoUrl', 'CleanStatus', 'OperatingHoursId'];
11

12
const NUMERIC_SF_TYPES = ['Currency', 'Double', 'Int', 'Percent', 'Long'];
13
const GROUP_PREFIXES = ['Billing', 'Shipping'];
14

15
export default class HandsontableApp extends LightningElement {
16
    data = [];
17
    columns = [];
18
    nestedHeaders = [];
19
    collapsibleColumns = [];
20
    error = null;
21
    _recordIds = [];
22
    _fieldApiNames = [];
23
    _objectInfo = null;
24
    _listRecords = null;
25
    _picklists = null;
26
    _recordTypeId = undefined;
27
    _listFields = undefined;
28

29
    @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
30
    wiredObjectInfo({ data, error }) {
31
        if (data) {
32
            this._objectInfo = data;
33
            this._recordTypeId = data.defaultRecordTypeId;
34
            this._buildGrid();
35
        } else if (error) {
36
            this.error = error.body?.message || 'Failed to load Account metadata';
37
        }
38
    }
39

40
    @wire(getPicklistValuesByRecordType, {
41
        objectApiName: ACCOUNT_OBJECT,
42
        recordTypeId: '$_recordTypeId',
43
    })
44
    wiredPicklists({ data, error }) {
45
        if (data) {
46
            this._picklists = data.picklistFieldValues;
47
            this._buildGrid();
48
        } else if (error) {
49
            this._picklists = {};
50
            this._buildGrid();
51
        }
52
    }
53

54
    @wire(getListInfoByName, {
55
        objectApiName: 'Account',
56
        listViewApiName: 'AllAccounts',
57
    })
58
    wiredListInfo({ data, error }) {
59
        if (data) {
60
            this._listFields = data.displayColumns.map(
61
                (column) => `Account.${column.fieldApiName}`,
62
            );
63
        } else if (error) {
64
            this.error = error.body?.message || 'Failed to load the list view';
65
        }
66
    }
67

68
    @wire(getListRecordsByName, {
69
        objectApiName: 'Account',
70
        listViewApiName: 'AllAccounts',
71
        fields: '$_listFields',
72
        pageSize: 50,
73
    })
74
    wiredAccounts({ data, error }) {
75
        if (data) {
76
            this._listRecords = data;
77
            this._buildGrid();
78
        } else if (error) {
79
            this.error = error.body?.message || 'Failed to load Accounts';
80
        }
81
    }
82
}

The builder maps each Salesforce data type to a Handsontable cell type. Picklist entries become the source of a dropdown, the numeric Salesforce types become numeric cells, and booleans become checkboxes:

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
_columnFor(fieldApiName, fieldInfo) {
3
    if (!fieldInfo) {
4
        return { type: 'text' };
5
    }
6

7
    if (fieldInfo.dataType === 'Picklist') {
8
        const picklist = this._picklists ? this._picklists[fieldApiName] : null;
9
        const values = [''];
10

11
        (picklist ? picklist.values : []).forEach((entry) => {
12
            values.push(entry.value);
13
        });
14

15
        return { type: 'dropdown', source: values };
16
    }
17

18
    if (NUMERIC_SF_TYPES.includes(fieldInfo.dataType)) {
19
        return { type: 'numeric' };
20
    }
21

22
    if (fieldInfo.dataType === 'Boolean') {
23
        return { type: 'checkbox' };
24
    }
25

26
    return { type: 'text' };
27
}

Fill the source with each entry’s value, not its label. The two differ on code-based picklists - a state field stores NC while its label reads North Carolina - and the record payload carries the value. Source the labels instead and the grid offers choices the API rejects: the cell shows NC, the dropdown lists North Carolina, and picking it fails the save with An error occurred while trying to update the record.

SKIP_FIELDS drops the fields that make no sense in a grid: system audit fields, and the ID and relationship fields whose values are not scalars. A relationship field such as Owner carries a nested record object rather than a string, so a cell would render [object Object].

Read the field list off the first returned record rather than off the metadata. getObjectInfo describes every field on the object, while the records carry only the fields the list view displays - the fields argument built from displayColumns. A column built from metadata that the payload does not carry renders empty even when the record holds a value - and an edit to that empty cell still writes, so it silently overwrites the stored value with whatever the user typed. The grid then re-renders from the refreshed payload, the cell goes blank again, and the write looks like it failed when it did not.

Accounts carry two obvious field groups, Billing* and Shipping*, which map onto nested headers with collapsible columns. The builder groups the fields by prefix, emits one header cell per group with a colspan, and flattens the records into the array of arrays the grid renders:

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
_groupOf(fieldName) {
3
    const prefix = GROUP_PREFIXES.find((candidate) => fieldName.startsWith(candidate));
4

5
    return prefix || 'General';
6
}
7

8
_buildGrid() {
9
    if (!this._objectInfo || !this._listRecords || !this._picklists) {
10
        return;
11
    }
12

13
    const records = this._listRecords.records;
14

15
    if (!records || records.length === 0) {
16
        this.error = 'No accounts found';
17

18
        return;
19
    }
20

21
    const fieldInfoMap = this._objectInfo.fields;
22
    const availableFields = Object.keys(records[0].fields)
23
        .filter((field) => !SKIP_FIELDS.includes(field));
24

25
    if (!availableFields.length) {
26
        return;
27
    }
28

29
    const groups = {};
30
    const groupOrder = [];
31

32
    availableFields.forEach((field) => {
33
        const group = this._groupOf(field);
34

35
        if (!groups[group]) {
36
            groups[group] = [];
37
            groupOrder.push(group);
38
        }
39

40
        groups[group].push(field);
41
    });
42

43
    groupOrder.sort((a, b) => {
44
        if (a === 'General') {
45
            return -1;
46
        }
47

48
        if (b === 'General') {
49
            return 1;
50
        }
51

52
        return a.localeCompare(b);
53
    });
54

55
    const orderedFields = [];
56

57
    groupOrder.forEach((group) => orderedFields.push(...groups[group]));
58

59
    const groupRow = [];
60
    const fieldRow = [];
61
    const collapsible = [];
62
    let colIndex = 0;
63

64
    groupOrder.forEach((group) => {
65
        const fields = groups[group];
66

67
        groupRow.push({ label: group, colspan: fields.length });
68
        collapsible.push({ row: -2, col: colIndex, collapsible: true });
69

70
        fields.forEach((field) => {
71
            const info = fieldInfoMap[field];
72

73
            fieldRow.push(info ? info.label : field);
74
        });
75

76
        colIndex += fields.length;
77
    });
78

79
    this.nestedHeaders = [groupRow, fieldRow];
80
    this.collapsibleColumns = collapsible;
81
    this.columns = orderedFields.map((field) => this._columnFor(field, fieldInfoMap[field]));
82

83
    this._fieldApiNames = orderedFields;
84
    this._recordIds = records.map((record) => record.id);
85
    this.data = records.map((record) => orderedFields.map((field) => {
86
        const value = record.fields[field]?.value;
87

88
        return value != null ? value : '';
89
    }));
90
    this.error = null;
91
}

The row: -2 in each collapsible entry addresses the upper of the two header rows. Header rows count upward from the data, so the group row of a two-row header is -2 and the field row is -1.

The _recordIds and _fieldApiNames arrays are what turn a cell coordinate back into a Salesforce field on a Salesforce record, which is how Step 6 saves an edit.

Stock All Accounts returns Name, Site, Phone, Type, and BillingStateCode - one dropdown and four text columns. Add Employees, Annual Revenue, or a checkbox field through List View Controls > Select Fields to Display, or point listViewApiName at your own list view, and those columns arrive as numeric and checkbox cells with no code change.

Account records rendered in the grid with grouped Billing and Shipping headers and a picklist dropdown open in a cell

Save changes back to Salesforce

Each grid event maps to one Lightning Data Service call. A cell edit resolves to a record ID and a field API name, and updateRecord writes it.

First, a helper for the error path. A rejected call puts An error occurred while trying to update the record. Please try again. in error.body.message, and the real reason in error.body.output.errors. Read the specific one when it is there:

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
_messageFrom(error, fallback) {
3
    const recordErrors = error?.body?.output?.errors;
4

5
    if (recordErrors && recordErrors.length) {
6
        return recordErrors.map((entry) => entry.message).join(' ');
7
    }
8

9
    return error?.body?.message || fallback;
10
}

Without it, a refused delete says “please try again” and the user retries forever. With it, the grid shows the org’s own explanation of what blocked the write.

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
handleCellChange(event) {
3
    const { physicalRow, col, newValue } = event.detail;
4
    const recordId = this._recordIds[physicalRow];
5
    const fieldName = this._fieldApiNames[col];
6

7
    if (!recordId || !fieldName) {
8
        return;
9
    }
10

11
    updateRecord({ fields: { Id: recordId, [fieldName]: newValue } })
12
        .catch((error) => {
13
            this.error = this._messageFrom(error, 'Save failed');
14
        });
15
}

A new row needs deferring. Handsontable fires afterCreateRow while the row is still empty, and a paste fills its cells afterwards, so creating the record immediately would save a blank one. Insert a null placeholder in _recordIds to keep the row-to-record mapping aligned, then read the row back on the next tick and create the record from whatever landed in it:

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
handleRowCreate(event) {
3
    const { index, physicalIndex, amount } = event.detail;
4
    const grid = this.template.querySelector('c-hot-grid');
5

6
    for (let i = 0; i < amount; i++) {
7
        const visualRow = index + i;
8
        const physicalRow = physicalIndex + i;
9

10
        this._recordIds.splice(physicalRow, 0, null);
11

12
        // eslint-disable-next-line @lwc/lwc/no-async-operation
13
        setTimeout(() => {
14
            const fields = {};
15

16
            this._fieldApiNames.forEach((field, col) => {
17
                const value = grid?.getDataAtCell?.(visualRow, col);
18

19
                if (value != null && value !== '') {
20
                    fields[field] = value;
21
                }
22
            });
23

24
            if (!fields.Name) {
25
                fields.Name = 'New Account';
26
            }
27

28
            createRecord({ apiName: 'Account', fields })
29
                .then((record) => {
30
                    this._recordIds[physicalRow] = record.id;
31
                })
32
                .catch((error) => {
33
                    this.error = this._messageFrom(error, 'Create failed');
34
                });
35
        }, 100);
36
    }
37
}

The handler uses both indexes on purpose: getDataAtCell() takes the visual row, while _recordIds keeps source order, so the placeholder and the saved ID land at the physical row.

The null placeholder also protects handleCellChange: a cell edit on a row whose record does not exist yet finds no ID and returns instead of writing to the wrong record.

createRecord does not refresh the list view, so the new row keeps whatever the user typed into it and shows no server-side values - the record exists, but getListRecordsByName still returns the page it fetched before the insert. Reload the page, or call refreshApex on the wired list result, when the row has to come back from the server.

Deletes are the one call the org refuses often, so the row removal is optimistic and reversible. Take the rows out of data right away, fire the deletes, and put the rows back at the same indexes if any of them rejects. The wrapper sends physical indexes, and on a sorted grid a contiguous visual selection maps to scattered physical rows, so the handler splices per row instead of once:

1
// force-app/main/default/lwc/handsontableApp/handsontableApp.js - inside the class
2
handleRowRemoveRequest(event) {
3
    const physicalRows = [...event.detail.physicalRows].sort((a, b) => a - b);
4
    const removed = physicalRows.map((row) => ({
5
        row,
6
        recordId: this._recordIds[row],
7
        values: this.data[row],
8
    }));
9

10
    [...removed].reverse().forEach(({ row }) => {
11
        this._recordIds.splice(row, 1);
12
    });
13
    this.data = this.data.filter((rowValues, row) => !physicalRows.includes(row));
14
    this.error = null;
15

16
    Promise.all(removed.map(({ recordId }) => (recordId ? deleteRecord(recordId) : Promise.resolve())))
17
        .catch((error) => {
18
            const restored = [...this.data];
19

20
            removed.forEach(({ row, recordId, values }) => {
21
                this._recordIds.splice(row, 0, recordId);
22
                restored.splice(row, 0, values);
23
            });
24
            this.data = restored;
25
            this.error = this._messageFrom(error, 'Delete failed');
26
        });
27
}

Capture the removed entries before you splice, because they are what the rollback puts back. Removal runs highest index first, and the rollback lowest first, so no splice shifts the indexes the next one uses. Each assignment to this.data is a new array, which is what pushes the change through the @api setter and into updateSettings().

Without the rollback the grid disagrees with the org: the row is gone locally, the record is not, and nothing says so until a reload. Refused deletes are common - Salesforce blocks deleting an account that has related cases or closed-won opportunities.

Expose this component so it can be dropped onto a Lightning page:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <isExposed>true</isExposed>
4
    <masterLabel>Handsontable</masterLabel>
5
    <targets>
6
        <target>lightning__AppPage</target>
7
        <target>lightning__HomePage</target>
8
        <target>lightning__RecordPage</target>
9
    </targets>
10
</LightningComponentBundle>

Deploy and open the grid

Drop the component onto an app page in Lightning App Builder, or deploy the page as metadata:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <flexiPageRegions>
4
        <itemInstances>
5
            <componentInstance>
6
                <componentName>handsontableApp</componentName>
7
                <identifier>c_handsontableApp</identifier>
8
            </componentInstance>
9
        </itemInstances>
10
        <name>main</name>
11
        <type>Region</type>
12
    </flexiPageRegions>
13
    <masterLabel>Handsontable Grid</masterLabel>
14
    <template>
15
        <name>flexipage:defaultAppHomeTemplate</name>
16
    </template>
17
    <type>AppPage</type>
18
</FlexiPage>

Leave the region’s mode out - <mode>Replace</mode> under flexipage:defaultAppHomeTemplate fails the deploy.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <flexiPage>Handsontable_Grid</flexiPage>
4
    <label>Handsontable Grid</label>
5
    <motif>Custom53: Bell</motif>
6
</CustomTab>

1
<?xml version="1.0" encoding="UTF-8"?>
2
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
3
    <label>Handsontable Grid</label>
4
    <hasActivationRequired>false</hasActivationRequired>
5
    <tabSettings>
6
        <tab>Handsontable_Grid</tab>
7
        <visibility>Visible</visibility>
8
    </tabSettings>
9
</PermissionSet>

Deploy, assign the permission set, and open the page:

1
sf project deploy start --source-dir force-app/main/default --target-org my-org
2
sf org assign permset --name Handsontable_Grid --target-org my-org
3
sf org open --target-org my-org --path "/lightning/n/Handsontable_Grid"

Edit a cell and reload the page. The value persists, because it went to the org and came back from it.

Known limitations

Tabbing in from another component focuses the grid without selecting a cell, so the arrow keys do nothing until the user clicks. Select one yourself on focusin - the web component recipe shows that listener.
The grid holds one list view page - 50 records here. For more, page through the list view or drive the grid with the dataProvider plugin against Apex.
One call per cell edit and per removed row, so a wide paste is one updateRecord per cell. Batch through Apex for bulk editing.
Dependent picklists offer every value. Each entry carries a validFor mask naming its controlling values, which _columnFor ignores, so a state field lists the states of every country. Filter values per row against the controlling field.
Field-level security is enforced by the API, not the grid: a read-only field still accepts input and fails on save. Mark those columns readOnly.

What you learned

The grid ships as a static resource and is created from window.Handsontable after its stylesheets resolve.
Field metadata generates the column configuration, and the list view payload decides which fields exist.
Settings cross as @api properties, forwarded through updateSettings() and deep-copied out of the reactive proxy.
Hooks become DOM events, each mapping to one Lightning Data Service call, with beforeRemoveRow making deletes reversible and the wrapper forwarding physical row indexes so a sorted grid still writes to the record the user edited.

Next steps

Shadow DOM - what Handsontable resolves at the shadow boundary, and how to load styles inside a shadow root.
Server-side data - move pagination, sorting, and filtering to the server for larger objects.
Cell types - extend the field-type mapping with dates, times, and custom editors.