@airstate/react

A set of powerful and opensource hooks for React that help you build any kind of real-time collaboration experiences.

Quick Links

• DOCS AirState React SDK
• AirState Cloud
• Self Hosting Instruction

Quickstart

Install

1pnpm add @airstate/client @airstate/react
2
3# or
4npm install --save @airstate/client @airstate/react

Note: @airstate/client is a required peer dependency of the React SDK

Configure

Get your appKey from console.airstate.dev

1import { configure } from '@airstate/client';
2
3// Call this before you start using the hooks
4// (it's safe to call outside react components)
5
6configure({
7    appKey: '[your app key]',
8});

If you want to connect to a self-hosted opensource version of our AirState server, please consult the docs on self-hosting

SharedState — useSharedState

This is a drop-in replacement for React's useState.

Every client at the same URL path will see the same data, and can update this data for it to be synced in real-time to all clients.

1// assume curent page url: example.com/tomato
2
3import {useSharedState} from '@airstate/react';
4
5export function App() {
6    // every client on example.com/tomato will see the
7    // save value in `state`
8    const [state, setState] = useSharedState<boolean>(false);
9
10    const toggle = () => {
11        setState((prev) => !prev);
12    };
13
14    return (
15        <button onClick={toggle}>
16            {state ? 'ON' : 'OFF'} - Click to Toggle
17        </button>
18    );
19}

useSharedState Kitchen Sink Example

Here's an example of using the hook with all the options and returns displayed.

1export function App() {
2    const [
3        
4        state,     // the data everyone sees
5        setState,  // change the data everyone sees
6        isReady,   // if the first-sync has occurred or not
7        
8    ] = useSharedState<TOptionalTypeOfState>(
9
10        { potato: 'brownish' },     // the initial state
11        
12        {
13            key: 'a-specific-room-key',          // if you don't want airstate to infer from url
14            token: 'jwt-signed-by-your-server',  // to maintain authentication & authorization
15            client: customClient                 // if you don't want to use the default client
16        }
17    );
18
19    return <>{/* ... */}</>;
20}

Read The Docs for more details on useSharedState and its options.

SharedPresence — useSharedPresence

Use this to build things like avatar stacks, live cursors, or location sharing. Use cases where allowing everyone to edit everyone's data doesn't make sense.

By default, every client at the same URL can see each other's data, but each client can only update their own data.

Here is an example to build real-time cursors:

1// assume current page url: example.com/tomato
2
3import { useSharedPresence } from '@airstate/react';
4
5export function App() {
6    // every client on example.com/tomato is now part of the same room
7    // and is sharing their dynamic state in real-time
8    
9    const { others, setDynamicState } = useSharedPresence({
10        peerKey: `${Math.random()}`, // replace this with any string that uniquely identifies the user
11        initialDynamicState: {
12            x: 0,
13            y: 0,
14        },
15    });
16
17    return (
18        // a blue 512 x 512 square
19        <div
20            className={'absolute bg-blue-200 top-0 left-0 w-[512] h-[512]'}
21            onMouseMove={(ev) => {
22                // update dynamic state on mouse move
23                setDynamicState({
24                    x: ev.clientX,
25                    y: ev.clientY,
26                });
27            }}>
28            {/* other people's cursors */}
29            {Object.values(others).map((other) => (
30                <div
31                    className={'absolute bg-red-500 w-[2] h-[2] rounded-full'}
32                    style={{
33                        top: (other.dynamicState?.state.y ?? 0) - 1,
34                        left: (other.dynamicState?.state.x ?? 0) - 1,
35                    }}></div>
36            ))}
37        </div>
38    );
39}

useSharedPresence Kitchen Sink Example

Here's a example of using the hook with all the return keys and options

1export function MaxedOut() {
2    const {
3        
4        self,              // this client's data
5        setDynamicState,   // set this client's dynamic state
6        others,            // everyone else's data (but not this client's)
7        summary,           // the number of peers that are online and focused
8        setFocus,          // set if this client is currently on the page and active
9    
10    } = useSharedPresence<TOptionalTypeOfDynamicState>({
11        
12        peerKey: `email-or-something-idk`,  // any string that uniquely identifies the user.
13        roomKey: 'a-specific-room-key',     // if you don't want airstate to infer from url
14        token: 'jwt-signed-by-your-server', // to maintain authentication & authorization
15        client: customClient,               // if you don't use to use the default client with default config
16       
17        initialDynamicState: {
18            x: 0,
19            y: 0,
20        },
21        
22    });
23
24    return <>{/* ... */}</>
25}

Read The Docs for more details on useSharedPresence and its options.

License

MIT