Handling collaboration and simultaneous editing

Coordinate edits between multiple users by detecting active edit state, intercepting local changes, and syncing structural and non-data changes across clients.

Handsontable doesn’t ship a transport layer or a conflict-resolution algorithm. To build collaborative editing, you send local changes to your own backend (for example, a WebSocket server) and apply changes from other collaborators back into the grid. This guide covers the hooks and methods you use on both sides of that flow.

The examples on this page simulate a remote collaborator locally, so they run without a real backend. In your app, replace the simulated call with the message you receive from your collaboration server.

Avoid overwriting a cell that’s being edited

Applying a remote change to a cell while the local user is still typing in it discards their in-progress edit. Before applying a remote change, check whether the target cell’s editor is open with getActiveEditor() and isOpened(). If it is, wait until the local edit finishes, then apply the remote change.

Use the beforeChange hook to read local edits and send them to other collaborators. Give changes that come from another collaborator a distinct source value, so your beforeChange handler doesn’t broadcast them again.

1
/* file: app.component.ts */
2
import { Component, OnDestroy, OnInit, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent, HotTableModule } from '@handsontable/angular-wrapper';
4
import Handsontable from 'handsontable/base';
5

6
// marks a change as coming from another collaborator, so it isn't broadcast again
7
const REMOTE_SOURCE = 'remotePeer';
8

9
@Component({
10
  selector: 'example1-collaboration',
11
  standalone: true,
12
  imports: [HotTableModule],
13
  template: ` <div class="example-controls-container">
14
      <p class="controls">{{ statusText }}</p>
15
    </div>
16
    <div>
17
      <hot-table [data]="hotData" [settings]="gridSettings"></hot-table>
18
    </div>`,
19
})
20
export class AppComponent implements OnInit, OnDestroy {
21
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
22

23
  statusText = 'A remote update to the first row arrives in 3 seconds.';
24

25
  private timeoutId?: ReturnType<typeof setTimeout>;
26

27
  readonly hotData = [
28
    ['Update onboarding flow', 'Ana García', 'In progress'],
29
    ['Fix invoice rounding bug', 'James Okafor', 'Blocked'],
30
    ['Write Q3 release notes', 'Li Wei', 'In progress'],
31
    ['Migrate auth service', 'Sofia Rossi', 'Done'],
32
    ['Design empty states', 'Diego Fernández', 'In progress'],
33
  ];
34

35
  readonly gridSettings: GridSettings = {
36
    colHeaders: ['Task', 'Assignee', 'Status'],
37
    rowHeaders: true,
38
    height: 'auto',
39
    beforeChange: (changes: (Handsontable.CellChange | null)[], source: Handsontable.ChangeSource | string) => {
40
      if (source === REMOTE_SOURCE || !changes) {
41
        return;
42
      }
43

44
      changes.forEach((change) => {
45
        if (!change) {
46
          return;
47
        }
48

49
        const [row, column, , newValue] = change;
50

51
        // send the local edit to your collaboration backend here
52
        console.log('Broadcasting local edit:', row, column, newValue);
53
      });
54
    },
55
  };
56

57
  ngOnInit(): void {
58
    // simulate an update coming from another collaborator - start editing the Status
59
    // cell in the first row before the timeout fires to see the update wait for you
60
    this.timeoutId = setTimeout(() => this.applyRemoteChange(0, 2, 'Done'), 3000);
61
  }
62

63
  ngOnDestroy(): void {
64
    clearTimeout(this.timeoutId);
65
  }
66

67
  applyRemoteChange(row: number, column: number, value: string): void {
68
    const hot = this.hotTable?.hotInstance;
69
    const editor = hot?.getActiveEditor();
70
    const editingSameCell = editor?.isOpened() && editor.row === row && editor.col === column;
71

72
    if (editingSameCell) {
73
      // don't overwrite a cell the local user is editing right now -
74
      // check again shortly, and apply the change once the local edit finishes
75
      this.timeoutId = setTimeout(() => this.applyRemoteChange(row, column, value), 300);
76

77
      return;
78
    }
79

80
    hot?.setDataAtCell(row, column, value, REMOTE_SOURCE);
81
    this.statusText = 'A collaborator marked "Update onboarding flow" as Done.';
82
  }
83
}
84
/* end-file */
85

86
/* file: app.config.ts */
87
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
88
import { registerAllModules } from 'handsontable/registry';
89
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
90

91
// register Handsontable's modules
92
registerAllModules();
93

94
export const appConfig: ApplicationConfig = {
95
  providers: [
96
    provideZoneChangeDetection({ eventCoalescing: true }),
97
    {
98
      provide: HOT_GLOBAL_CONFIG,
99
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
100
    },
101
  ],
102
};
103
/* end-file */

1
<div>
2
    <example1-collaboration></example1-collaboration>
3
</div>

A simulated remote update to the Status column of the first row arrives 3 seconds after the example loads. Start editing that cell before then, and the remote change waits until you finish.

Guard and replay structural changes

Row and column changes need the same two-way handling as cell data. Use beforeCreateRow, beforeRemoveRow, beforeCreateCol, and beforeRemoveCol to read local structural changes and forward them to other collaborators. Each hook receives the source argument you passed in, so you can skip re-broadcasting a change that a collaborator sent you.

To apply a structural change from another collaborator, call alter() with the same source value:

1
const configurationOptions = {
2
  beforeCreateRow(index, amount, source) {
3
    if (source === 'remotePeer') {
4
      // let a structural change from another collaborator through
5
      return;
6
    }
7

8
    // send the local structural change to your collaboration backend here
9
  },
10
  beforeRemoveRow(index, amount, physicalRows, source) {
11
    if (source === 'remotePeer') {
12
      return;
13
    }
14

15
    // send the local structural change to your collaboration backend here
16
  },
17
};
18

19
// apply a structural change received from another collaborator
20
hot.alter('insert_row_below', 2, 1, 'remotePeer');

Sync cell metadata, comments, merged cells, and borders

Collaborators also share state that isn’t part of the cell value. setCellMeta() writes arbitrary metadata (for example, a className that flags a cell as locked by another user), but it doesn’t repaint the grid on its own - call render() afterward.

The Comments, MergeCells, and CustomBorders plugins expose methods you can call with data received from another collaborator:

1
// share arbitrary metadata, then repaint to apply it
2
hot.setCellMeta(1, 2, 'className', 'is-locked-by-remote-user');
3
hot.render();
4

5
// mirror a comment left by another collaborator
6
hot.getPlugin('comments').setCommentAtCell(1, 2, 'Reviewed - looks good.');
7

8
// mirror a merged area created by another collaborator
9
hot.getPlugin('mergeCells').merge(0, 0, 0, 1);
10

11
// mirror a border added by another collaborator
12
hot.getPlugin('customBorders').setBorders([[1, 1, 1, 1]], { start: { width: 2, color: '#2563eb' } });

The Comments plugin stores comments as cell meta, so setCommentAtCell() and removeCommentAtCell() also trigger beforeSetCellMeta and afterSetCellMeta - handle comment changes there if you’re already syncing cell meta through those hooks.

Result

After completing this guide, your grid detects when a remote update would overwrite a cell the local user is actively editing, broadcasts local data and structural changes to other collaborators, and mirrors remote changes to cell data, rows, columns, comments, merged cells, and borders.

Core methods

Hooks