Multiplayer editing with Liveblocks

In this tutorial, you will turn Handsontable into a multiplayer grid with Liveblocks. You will learn how to sync cell values through Liveblocks Storage, share each user’s selected cell through Presence, and draw live selection borders for other users with a custom cell renderer.

Overview

Try the live example on Liveblocks

Multiplayer spreadsheet editing with Liveblocks: several users editing the same grid with colored selection cursors

This recipe connects Handsontable to Liveblocks, a hosted real-time collaboration service. Two kinds of state travel over the Liveblocks room. The grid’s cell values live in Storage (the shared document every user edits), and each user’s currently selected cell lives in Presence (ephemeral per-user state). A custom renderer reads the presence of other users and paints a colored border on the cells they have selected, so everyone sees where everyone else is working.

Liveblocks runs against a hosted backend that needs your own API key, so the grid cannot run inside this page. The code below is the complete client. Follow the steps to wire it into a Next.js app, or open the live example above.

Difficulty: Intermediate Time: ~20 minutes Stack: Next.js (App Router), React, Liveblocks, Handsontable, @handsontable/react-wrapper

What You’ll Build

A shared data grid where every connected user:

Edits the same cells in real time, so a change made by one user appears in every other user’s grid
Sees a colored border on the cell each other user has selected, with stacked borders when several users sit on the same cell
Joins through a single Liveblocks room with an initial 10×5 empty grid

Before you begin

This recipe assumes a Next.js app using the App Router. You also need a free Liveblocks account to get a public API key.

Install the dependencies:

1
npm install @liveblocks/client @liveblocks/react @handsontable/react-wrapper handsontable

Scaffold the Liveblocks configuration:

1
npx create-liveblocks-app@latest --init --framework react

Copy your public API key from the Liveblocks dashboard and use it in place of {{PUBLIC_KEY}} in Room.tsx (Step 2).

Define Presence and Storage types
TypeScript
```
1
import type { LiveList } from "@liveblocks/client";
2

3
export const GRID_ROWS = 10;
4
export const GRID_COLS = 5;
5

6
declare global {
7
  interface Liveblocks {
8
    Presence: {
9
      selectedCell: { row: number; col: number } | null;
10
    };
11
    Storage: {
12
      grid: LiveList<LiveList<string>>;
13
    };
14
  }
15
}
```
What’s happening: The global Liveblocks interface tells the Liveblocks hooks the exact shape of your room. Storage is the persisted, shared document: a LiveList of rows, each itself a LiveList of cell strings, so it can be mutated cell-by-cell without replacing the whole grid. Presence is each user’s ephemeral state: the row and column of their selected cell, or null when nothing is selected.

Why a nested LiveList? A LiveList<LiveList<string>> lets two users edit different cells at the same time without conflict. Setting one cell calls row.set(colIndex, value) on only that inner list, so Liveblocks merges concurrent edits instead of replacing the entire grid.

Set up the room

1
"use client";
2

3
import { LiveList } from "@liveblocks/client";
4
import { ReactNode } from "react";
5
import {
6
  LiveblocksProvider,
7
  RoomProvider,
8
  ClientSideSuspense,
9
} from "@liveblocks/react/suspense";
10
import { GRID_COLS, GRID_ROWS } from "./liveblocks.config";
11

12
export function Room({ children }: { children: ReactNode }) {
13
  return (
14
    <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
15
      <RoomProvider
16
        id="my-room"
17
        initialPresence={{ selectedCell: null }}
18
        initialStorage={{
19
          grid: new LiveList(
20
            Array.from(
21
              { length: GRID_ROWS },
22
              () => new LiveList(Array.from({ length: GRID_COLS }, () => ""))
23
            )
24
          ),
25
        }}
26
      >
27
        <ClientSideSuspense fallback={<div>Loading…</div>}>
28
          {children}
29
        </ClientSideSuspense>
30
      </RoomProvider>
31
    </LiveblocksProvider>
32
  );
33
}

What’s happening: LiveblocksProvider connects the app to your Liveblocks project with the public API key. RoomProvider joins the room "my-room" and seeds it: initialPresence starts every user with no selected cell, and initialStorage builds a 10×5 grid of empty strings the first time the room is created. ClientSideSuspense holds back the children until the room’s storage has loaded.

Wire up the page

1
import { Room } from "./Room";
2
import { Table } from "./Table";
3

4
export default function Page() {
5
  return (
6
    <Room>
7
      <Table />
8
    </Room>
9
  );
10
}

What’s happening: The page renders the Table inside the Room, so every Liveblocks hook the table uses resolves against the joined room.

Read and write cell values through Storage

1
"use client";
2

3
import { shallow } from "@liveblocks/client";
4
import { HotTable } from "@handsontable/react-wrapper";
5
import { registerAllModules } from "handsontable/registry";
6
import { textRenderer } from "handsontable/renderers";
7
import {
8
  useMutation,
9
  useOthersListener,
10
  useStorage,
11
} from "@liveblocks/react/suspense";
12
import { useCallback, useRef } from "react";
13
import { GRID_COLS, GRID_ROWS } from "./liveblocks.config";
14

15
registerAllModules();
16

17
export function Table() {
18
  const hotRef = useRef(null);
19

20
  // Get the realtime grid contents from Liveblocks Storage
21
  const data = useStorage(
22
    (root) =>
23
      root.grid.map((row) =>
24
        Array.from({ length: GRID_COLS }, (_, c) => String(row[c] ?? ""))
25
      ),
26
    shallow
27
  );
28

29
  // Update a cell's value
30
  const updateCell = useMutation(({ storage }, rowIndex, colIndex, value) => {
31
    const grid = storage.get("grid");
32
    const row = grid.get(rowIndex);
33
    if (row) {
34
      row.set(colIndex, value);
35
    }
36
  }, []);
37

38
  // Update the grid when a cell is changed
39
  const afterChange = useCallback(
40
    (changes, source) => {
41
      if (!changes || source === "loadData") {
42
        return;
43
      }
44

45
      for (const [row, prop, , newVal] of changes) {
46
        if (typeof prop !== "number") {
47
          continue;
48
        }
49

50
        updateCell(
51
          row,
52
          prop,
53
          newVal === null || newVal === undefined ? "" : String(newVal)
54
        );
55
      }
56
    },
57
    [updateCell]
58
  );
59

60
  // Sync selected cell to presence
61
  const syncSelectedCellToPresence = useMutation(({ setMyPresence }, row, col) => {
62
    setMyPresence({
63
      selectedCell: { row: row < 0 ? 0 : row, col: col < 0 ? 0 : col },
64
    });
65
  }, []);
66

67
  const clearSelectedCellPresence = useMutation(({ setMyPresence }) => {
68
    setMyPresence({ selectedCell: null });
69
  }, []);
70

71
  // Render presence inside cells
72
  const renderDataCell = useMutation(({ others }, ...props) => {
73
    textRenderer(...props);
74
    const [, td, row, col] = props;
75

76
    // Find users who have selected this cell
77
    const selectedOthers = others.filter(
78
      (o) =>
79
        o.presence.selectedCell?.row === row &&
80
        o.presence.selectedCell?.col === col
81
    );
82

83
    if (!selectedOthers.length) {
84
      td.style.boxShadow = "";
85
      return;
86
    }
87

88
    // Add inner borders for selected users
89
    td.style.boxShadow = selectedOthers
90
      .map((p, i) => `inset 0 0 0 ${2 + i * 2}px ${p.info.color}`)
91
      .join(", ");
92
  }, []);
93

94
  // Re-render the table when others update their presence
95
  useOthersListener(({ type }) => {
96
    if (type === "update") {
97
      hotRef.current?.hotInstance?.render();
98
    }
99
  });
100

101
  return (
102
    <HotTable
103
      ref={hotRef}
104
      data={data}
105
      hotRenderer={renderDataCell}
106
      afterChange={afterChange}
107
      afterSelection={syncSelectedCellToPresence}
108
      afterDeselect={clearSelectedCellPresence}
109
      colHeaders={true}
110
      rowHeaders={true}
111
      height={400}
112
      width={600}
113
      licenseKey="non-commercial-and-evaluation"
114
      autoWrapRow={true}
115
      autoWrapCol={true}
116
    />
117
  );
118
}

The grid component above is the full client. The next steps walk through its three responsibilities, starting with reading and writing cell values:

1
const data = useStorage(
2
  (root) =>
3
    root.grid.map((row) =>
4
      Array.from({ length: GRID_COLS }, (_, c) => String(row[c] ?? ""))
5
    ),
6
  shallow
7
);
8

9
const updateCell = useMutation(
10
  ({ storage }, rowIndex: number, colIndex: number, value: string) => {
11
    const grid = storage.get("grid");
12
    const row = grid.get(rowIndex);
13
    if (row) {
14
      row.set(colIndex, value);
15
    }
16
  },
17
  []
18
);

What’s happening: useStorage projects the LiveList grid into a plain string[][] that Handsontable accepts as its data, and re-runs whenever storage changes, so a remote edit flows straight into the grid. The shallow comparison stops needless re-renders when the projected array is structurally unchanged. useMutation returns updateCell, which writes a single cell back into storage; Liveblocks broadcasts that write to every other user.

Why setDataAtCell is not used here: the grid’s data is driven entirely by useStorage. You never imperatively set cell values. You mutate storage, and the storage subscription re-feeds data, which keeps one source of truth.

Sync edits and selection to the room

1
const afterChange = useCallback(
2
  (changes: CellChange[] | null, source: ChangeSource) => {
3
    if (!changes || source === "loadData") {
4
      return;
5
    }
6

7
    for (const [row, prop, , newVal] of changes) {
8
      if (typeof prop !== "number") {
9
        continue;
10
      }
11

12
      updateCell(
13
        row,
14
        prop,
15
        newVal === null || newVal === undefined ? "" : String(newVal)
16
      );
17
    }
18
  },
19
  [updateCell]
20
);
21

22
const syncSelectedCellToPresence = useMutation(
23
  ({ setMyPresence }, row: number, col: number) => {
24
    setMyPresence({
25
      selectedCell: { row: row < 0 ? 0 : row, col: col < 0 ? 0 : col },
26
    });
27
  },
28
  []
29
);
30

31
const clearSelectedCellPresence = useMutation(({ setMyPresence }) => {
32
  setMyPresence({ selectedCell: null });
33
}, []);

What’s happening: afterChange runs on every local edit. It skips the initial loadData pass, then calls updateCell for each changed cell so the edit reaches storage. afterSelection is wired to syncSelectedCellToPresence, which writes the selected cell into the user’s presence; the < 0 ? 0 guards clamp Handsontable’s header coordinates (-1) to a valid cell. afterDeselect clears presence so the border disappears when the user clicks away.

Render other users’ selections

1
const renderDataCell = useMutation(
2
  ({ others }, ...props: Parameters<typeof textRenderer>) => {
3
    textRenderer(...props);
4
    const [, td, row, col] = props;
5

6
    const selectedOthers = others.filter(
7
      (o) =>
8
        o.presence.selectedCell?.row === row &&
9
        o.presence.selectedCell?.col === col
10
    );
11

12
    if (!selectedOthers.length) {
13
      td.style.boxShadow = "";
14
      return;
15
    }
16

17
    td.style.boxShadow = selectedOthers
18
      .map((p, i) => `inset 0 0 0 ${2 + i * 2}px ${p.info.color}`)
19
      .join(", ");
20
  },
21
  []
22
);
23

24
useOthersListener(({ type }) => {
25
  if (type === "update") {
26
    hotRef.current?.hotInstance?.render();
27
  }
28
});

What’s happening: renderDataCell is passed to Handsontable as hotRenderer. It first calls the built-in textRenderer to paint the value, then reads others (the presence of every other user in the room) and finds those whose selectedCell matches this cell. For each match it stacks an inset box-shadow in that user’s color, so two users on the same cell show two nested borders. useOthersListener re-renders the grid whenever another user’s presence changes, so borders follow them as they move.

Why force a render? Handsontable does not know that remote presence changed. useOthersListener bridges that gap: on every presence update, it calls hotInstance.render() so the renderer re-runs with the new selection data.

How It Works - Complete Flow

A user joins: RoomProvider connects to "my-room"; ClientSideSuspense waits for storage, then useStorage feeds the 10×5 grid into Handsontable.
User A edits a cell: afterChange fires, updateCell writes the value into the LiveList grid in storage.
Liveblocks broadcasts the storage change to everyone in the room.
User B’s grid updates: their useStorage subscription re-runs, returning the new string[][], and Handsontable shows the edit, with no manual setDataAtCell call.
User A selects a cell: afterSelection writes { row, col } into User A’s presence via setMyPresence.
User B sees the selection: useOthersListener catches the presence update and re-renders; renderDataCell finds User A among others on that cell and draws a border in User A’s color.
User A clicks away: afterDeselect sets presence back to null, and User B’s next render clears the border.

What you learned

How to model shared grid data as a nested Liveblocks LiveList so concurrent cell edits merge instead of overwriting each other.
How useStorage makes Liveblocks storage the single source of truth for Handsontable’s data, removing the need for imperative cell updates.
How useMutation writes both shared storage (cell values) and per-user presence (selection) back to the room.
How a custom hotRenderer reads the presence of others and paints stacked selection borders in each user’s color.
How useOthersListener re-renders the grid when remote presence changes so live cursors stay in sync.

Next steps

Add authentication so only permitted users can join a room, instead of using a public API key in the client.
Add comments anchored to cells with the Liveblocks comments recipe.
Show a live avatar stack of who is in the room using the same others presence data.
Compare with the WebSocket updates recipe to see a backend-agnostic real-time pattern that updates cells with setDataAtCell.