Guides / Get started - Get started with React

This guide assumes that you're already familiar with React.

Alternatively, you can copy this example and follow the instructions in the README:

Run the following command to install Liveblocks packages:

npm install @liveblocks/client @liveblocks/react

@liveblocks/client lets you connect to Liveblocks servers.
@liveblocks/react contains react utilities to make it easier to consume @liveblocks/client.

To connect to Liveblocks, you should use the LiveblocksProvider at the root of your React app. This component wraps all the pages of your website and allows you to use the Liveblocks hooks in any React component.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import { createClient } from "@liveblocks/client";
import { LiveblocksProvider } from "@liveblocks/react";
// Create a liveblocks client
// Replace this key with your secret key provided at https://liveblocks.io/dashboard/apikeys
const client = createClient({
publicApiKey: "pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
});
ReactDOM.render(
<React.StrictMode>
<LiveblocksProvider client={client}>
<App />
</LiveblocksProvider>
</React.StrictMode>,
document.getElementById('root')
);

Liveblocks should now be installed into your project!

A room is the virtual space where people collaborate. To create a multiplayer experience, you’ll need to connect your users to a Liveblocks room following the instructions below.

You can easily connect to a room by using RoomProvider inside your App.js React component as shown below.

1
2
3
4
5
6
7
8
9
10
import React from 'react';
import { RoomProvider } from "@liveblocks/react";
export default function App() {
return (
<RoomProvider id="your-room-id">
{/* Child components will have access to the room data */}
</RoomProvider>
)
}

Now that we have our room setup, we can start using the Liveblocks React hooks to share any kind of data between users. For instance, useOthers allows us to list all the people that are currently connected to the room.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import React from 'react';
import { RoomProvider, useOthers } from "@liveblocks/react";
export default function App() {
return (
<RoomProvider id="your-room-id">
<ConnectedUsers />
</RoomProvider>
)
}
function ConnectedUsers() {
const others = useOthers();
if (others.count === 0) {
return "You’re the only one here.";
} else if (others.count === 1) {
return "There is one other person here.";
} else {
return "There are " + others.count + " other people here.";
}
}

Using the public key allows you to use Liveblocks without implementing your own authentication endpoint. It’s great for prototyping and marketing websites.

If you want to implement your own security and define if the current user has access to a specific room, you can follow the Authentication guide.

If you are using Next.js, you can also check the Next.js Authentication guide.

Explore our examples below to see what you can do with Liveblocks.

  • Image of Live cursors

    Live cursors

    4 examples
    View
  • Image of Live avatar stack

    Live avatar stack

    2 examples
    View
  • Image of Live selection

    Live selection

    3 examples
    View