Tutorials - Creating a collaborative online whiteboard with React, Redux, and Liveblocks

In this 25-minute guide, we’ll be building a collaborative whiteboard app using React, Redux and Liveblocks. As users add and move rectangles in a canvas, changes will be automatically synced and persisted, allowing for a canvas that updates in real-time across clients. Users will also be able to see other users selections, and undo and redo actions.

This guide assumes that you’re already familiar with React and Redux. If you’re not using Redux, we recommend reading one of our dedicated whiteboard tutorials:

The source code for this guide is available on github.

Install Liveblocks into your project

Install Liveblocks packages

Create a new app with create-react-app:

npx create-react-app redux-whiteboard

Then run the following command to install the Liveblocks packages and Redux:

npm install redux react-redux @reduxjs/toolkit @liveblocks/client @liveblocks/redux

Connect to Liveblocks servers

In order to use Liveblocks, we’ll need to sign up and get an API key. Create an account, then navigate to the dashboard to find your public key. It should start with pk_.

Public vs secret key

With a secret key, you can control who can access the room. it’s more secure but you need your own back-end endpoint. For this tutorial, we’ll go with a public key. For more info, see the authentication guide.

Create a new file src/store.js and initialize the Liveblocks client with your public API key. Then add our enhancer to your store configuration.

import { createClient } from "@liveblocks/client";import { enhancer } from "@liveblocks/redux";import { configureStore, createSlice } from "@reduxjs/toolkit";
export const client = createClient({  publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
const initialState = {  /* default state will go there */};
const slice = createSlice({  name: "state",  initialState,  reducers: {    /* Reducer logic will go there */  },});
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,      }),    ],  });}
const store = makeStore();
export default store;

And edit src/index.js to add the react-redux provider to your app:

import React from "react";import ReactDOM from "react-dom";import "./index.css";import App from "./App";
import { Provider } from "react-redux";import store from "./store";
ReactDOM.render(  <React.StrictMode>    <Provider store={store}>      <App />    </Provider>  </React.StrictMode>,  document.getElementById("root"));

Connect to a Liveblocks room

Liveblocks uses the concept of rooms, separate virtual spaces where people can collaborate. To create a multiplayer experience, multiple users must be connected to the same room.

Our enhancer is responsible to enter or leave a room when you dispatch enterRoom or leaveRoom.

In our main component, we want to connect to the Liveblocks room when the component does mount, and leave the room when it unmounts.

import { useEffect } from "react";import "./App.css";import { useDispatch } from "react-redux";import { actions } from "@liveblocks/redux";
const roomId = "redux-whiteboard";
export default function App() {  const dispatch = useDispatch();
  useEffect(() => {    dispatch(actions.enterRoom(roomId));
    return () => {      dispatch(actions.leaveRoom(roomId));    };  }, [dispatch]);
  return <div className="container">Whiteboard app</div>;}

Create a canvas

Whiteboard shapes will be stored even after all users disconnect, so we will use Liveblocks storage to persist them.

Add a shapes property to your store, and configure the enhancer to sync and persist them with Liveblocks.

To achieve that, we are going to use the enhancer option storageMapping: { shapes: true }. It means that the part of the state named shapes should be automatically synced with Liveblocks Storage.

import { createClient } from "@liveblocks/client";import { enhancer } from "@liveblocks/redux";import { configureStore, createSlice } from "@reduxjs/toolkit";
export const client = createClient({  publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
const initialState = {  shapes: {},};
const slice = createSlice({  name: "state",  initialState,  reducers: {    /* Reducer logic will go there */  },});
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,        storageMapping: { shapes: true },      }),    ],  });}
const store = makeStore();
export default store;

Afterwards, we draw the shapes in our canvas. To keep it simple for the tutorial, we are going to only support rectangle.

import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const dispatch = useDispatch();
  useEffect(() => {    dispatch(      actions.enterRoom(roomId, {        shapes: {},      })    );
    return () => {      dispatch(actions.leaveRoom(roomId));    };  }, [dispatch]);
  if (isLoading) {    return <div className="loading">Loading</div>;  }
  return (    <div className="canvas">      {Object.entries(shapes).map(([shapeId, shape]) => {        return <Rectangle key={shapeId} shape={shape} />;      })}    </div>  );}
const Rectangle = ({ shape }) => {  return (    <div      className="rectangle"      style={{        transform: `translate(${shape.x}px, ${shape.y}px)`,        backgroundColor: shape.fill ? shape.fill : "#CCC",      }}    ></div>  );};

Place the following within src/App.css, and then you will be able to insert rectangular shapes into the whiteboard.

Insert rectangles

Currently our whiteboard is empty, and there’s no way to add rectangles. Let’s create a button that adds a randomly placed rectangle to the board.

Add a new action to your store that randomly insert a rectangle on the board.

import { createClient } from "@liveblocks/client";import { enhancer } from "@liveblocks/redux";import { configureStore, createSlice } from "@reduxjs/toolkit";
export const client = createClient({  publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
const COLORS = ["#DC2626", "#D97706", "#059669", "#7C3AED", "#DB2777"];
function getRandomInt(max) {  return Math.floor(Math.random() * max);}
function getRandomColor() {  return COLORS[getRandomInt(COLORS.length)];}
const initialState = {  shapes: {},};
const slice = createSlice({  name: "state",  initialState,  reducers: {    insertRectangle: (state) => {      const shapeId = Date.now().toString();      const shape = {        x: getRandomInt(300),        y: getRandomInt(300),        fill: getRandomColor(),      };      state.shapes[shapeId] = shape;    },  },});
export const { insertRectangle } = slice.actions;
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,        storageMapping: { shapes: true },      }),    ],  });}
const store = makeStore();
export default store;

Then add a button to dispatch this action from the board.

import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import { insertRectangle } from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div className="canvas">        {Object.entries(shapes).map(([shapeId, shape]) => {          return <Rectangle key={shapeId} shape={shape} />;        })}      </div>      <div className="toolbar">        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>      </div>    </>  );}
/* Rectangle */

Add selection

We can use Liveblocks to display which shape each user is currently selecting, in this case by adding a border to the rectangles. We’ll use a blue border to represent the local user, and green borders for remote users.

Any online user could select a shape, and we need to keep track of this, so it’s best if each user holds their own selectedShape property.

Luckily, Liveblocks uses the concept of presence to handle these temporary states. A user’s presence can be used to represent the position of a cursor on screen, or in this case the selected shape in a design tool.

We want to add some data to our Redux store, selectedShape will contain the selected shape id. selectedShape will be set when the user select or insert a rectangle.

The middleware option presenceMapping: { selectedShape: true } means that we want to automatically sync the part of the state named selectedShape to Liveblocks Presence.

/* ... */
const initialState = {  shapes: {},  selectedShape: null,};
const slice = createSlice({  name: "state",  initialState,  reducers: {    insertRectangle: (state) => {      /* ... */    },    onShapePointerDown: (state, action) => {      state.selectedShape = action.payload;    },  },});
export const { insertRectangle, onShapePointerDown } = slice.actions;
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,        storageMapping: { shapes: true },        presenceMapping: { selectedShape: true },      }),    ],  });}
const store = makeStore();
export default store;

Update your App and Rectangle components to show if a shape is selected by the current user or someone else in the room.

import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import { insertRectangle, onShapePointerDown } from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const others = useSelector((state) => state.liveblocks.others);  const selectedShape = useSelector((state) => state.selectedShape);  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div className="canvas">        {Object.entries(shapes).map(([shapeId, shape]) => {          let selectionColor = "transparent";
          if (selectedShape === shapeId) {            selectionColor = "blue";          } else if (            others.some((user) => user.presence?.selectedShape === shapeId)          ) {            selectionColor = "green";          }
          return (            <Rectangle              key={shapeId}              id={shapeId}              shape={shape}              selectionColor={selectionColor}            />          );        })}      </div>      <div className="toolbar">        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>      </div>    </>  );}
const Rectangle = ({ shape, selectionColor, id }) => {  const dispatch = useDispatch();
  return (    <div      className="rectangle"      style={{        transform: `translate(${shape.x}px, ${shape.y}px)`,        backgroundColor: shape.fill ? shape.fill : "#CCC",        borderColor: selectionColor,      }}      onPointerDown={(e) => {        e.stopPropagation();        dispatch(onShapePointerDown(id));      }}    ></div>  );};

Delete rectangles

Now that users can select rectangles, we can add a button that allow deleting rectangles too.

Create a deleteShape action to remove the selected shape from shapes, and then reset the user’s selection:

/* ... */
const initialState = {  shapes: {},  selectedShape: null,};
const slice = createSlice({  name: "state",  initialState,  reducers: {    insertRectangle: (state) => {      const shapeId = Date.now().toString();      const shape = {        x: getRandomInt(300),        y: getRandomInt(300),        fill: getRandomColor(),      };      state.shapes[shapeId] = shape;      state.selectedShape = shapeId;    },    onShapePointerDown: (state, action) => {      /* ... */    },    deleteShape: (state) => {      if (state.selectedShape) {        delete state.shapes[state.selectedShape];        state.selectedShape = null;      }    },  },});
export const { insertRectangle, onShapePointerDown, deleteShape } =  slice.actions;
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,        presenceMapping: { selectedShape: true },        storageMapping: { shapes: true },      }),    ],  });}
const store = makeStore();
export default store;
import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import { insertRectangle, onShapePointerDown, deleteShape } from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const selectedShape = useSelector((state) => state.selectedShape);  const others = useSelector((state) => state.liveblocks.others);
  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div className="canvas">{/* ... */}</div>      <div className="toolbar">        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>        <button          onClick={() => dispatch(deleteShape())}          disabled={selectedShape == null}        >          Delete        </button>      </div>    </>  );}
/* Rectangle */

Move rectangles

Let’s move some rectangles!

To allow users to move rectangles, we’ll update the x and y properties of the selected shape when a user drags it:

/* ... */
const initialState = {  shapes: {},  selectedShape: null,  isDragging: false,};
const slice = createSlice({  name: "state",  initialState,  reducers: {    insertRectangle: (state) => {      /* ... */    },    onShapePointerDown: (state, action) => {      state.selectedShape = action.payload;      state.isDragging = true;    },    deleteShape: (state) => {      /* ... */    },    onCanvasPointerUp: (state) => {      state.isDragging = false;    },    onCanvasPointerMove: (state, action) => {      if (state.isDragging && state.selectedShape) {        state.shapes[state.selectedShape].x = action.payload.x - 50;        state.shapes[state.selectedShape].y = action.payload.y - 50;      }    },  },});
export const {  insertRectangle,  onShapePointerDown,  deleteShape,  onCanvasPointerUp,  onCanvasPointerMove,} = slice.actions;
export function makeStore() {  return configureStore({    reducer: slice.reducer,    enhancers: [      enhancer({        client,        presenceMapping: { selectedShape: true },        storageMapping: { shapes: true },      }),    ],  });}
const store = makeStore();
export default store;
import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import {  insertRectangle,  onShapePointerDown,  deleteShape,  onCanvasPointerUp,  onCanvasPointerMove,} from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const selectedShape = useSelector((state) => state.selectedShape);  const others = useSelector((state) => state.liveblocks.others);
  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div        className="canvas"        onPointerMove={(e) => {          e.preventDefault();          dispatch(onCanvasPointerMove({ x: e.clientX, y: e.clientY }));        }}        onPointerUp={() => {          dispatch(onCanvasPointerUp());        }}      >        {/* ... */}      </div>      <div className="toolbar">{/* ... */}</div>    </>  );}
/* ... */

Multiplayer undo/redo

With Liveblocks, you can enable multiplayer undo/redo in just a few lines of code.

Add two buttons to the toolbar and bind them to room.history.undo and room.history.redo. These functions only impact modifications made to the room’s storage.

import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import {  insertRectangle,  onShapePointerDown,  deleteShape,  onCanvasPointerUp,  onCanvasPointerMove,  client,} from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const selectedShape = useSelector((state) => state.selectedShape);  const others = useSelector((state) => state.liveblocks.others);
  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div        className="canvas"        onPointerMove={(e) => {          /* ... */        }}        onPointerUp={() => {          /* ... */        }}      >        {/* ... */}      </div>      <div className="toolbar">        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>        <button          onClick={() => dispatch(deleteShape())}          disabled={selectedShape == null}        >          Delete        </button>        <button onClick={() => client.getRoom(roomId).history.undo()}>          Undo        </button>        <button onClick={() => client.getRoom(roomId).history.redo()}>          Redo        </button>      </div>    </>  );}
/* Rectangle */

Pause and resume history

When a user moves a rectangle, a large number of actions are sent to Liveblocks and live synced, enabling other users to see movements in real-time.

The problem with this is that the undo button returns the rectangle to the last intermediary position, and not the position where the rectangle started its movement. We can fix this by pausing storage history until the move has completed.

We’ll use history.pause to disable adding any positions to the history stack while the cursors moves, and then call history.resume afterwards.

import { useEffect } from "react";import "./App.css";import { useDispatch, useSelector } from "react-redux";import { actions } from "@liveblocks/redux";
import {  insertRectangle,  onShapePointerDown,  deleteShape,  onCanvasPointerUp,  onCanvasPointerMove,  client,} from "./store";
const roomId = "redux-whiteboard";
export default function App() {  const shapes = useSelector((state) => state.shapes);  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);  const selectedShape = useSelector((state) => state.selectedShape);  const others = useSelector((state) => state.liveblocks.others);
  const dispatch = useDispatch();
  /* ... */
  return (    <>      <div        className="canvas"        onPointerMove={(e) => {          /* ... */        }}        onPointerUp={() => {          dispatch(onCanvasPointerUp());          client.getRoom(roomId).history.resume();        }}      >        {/* ... */}      </div>      <div className="toolbar">{/* ... */}</div>    </>  );}
const Rectangle = ({ shape, selectionColor, id }) => {  const dispatch = useDispatch();
  return (    <div      className="rectangle"      style={{        transform: `translate(${shape.x}px, ${shape.y}px)`,        backgroundColor: shape.fill ? shape.fill : "#CCC",        borderColor: selectionColor,      }}      onPointerDown={(e) => {        e.stopPropagation();        client.getRoom(roomId).history.pause();        dispatch(onShapePointerDown(id));      }}    ></div>  );};

Voilà! We have a working collaborative whiteboard app, with persistent data storage.

Summary

In this tutorial, we’ve learnt about the concept of rooms, presence, and others. We've also learnt how to put all these into practice, and how to persist state using storage too.

You can see some stats about the room you created in your dashboard.

Liveblocks dashboard

Next steps

© 2023 Liveblocks Inc.Edit this page