React Hooks

Incorporate Spaces into your React application with idiomatic and user-friendly React Hooks.

This package enables you to:

• Interact with Ably Spaces using a React Hook
• Subscribe to events in a space
• Retrieve the membership of a space
• Set the location of space members
• Acquire locks on components within a space
• Set the position of members’ cursors in a space

The following hooks are available:

useSpace

The useSpace hook lets you subscribe to the current Space and receive Space state events and get current Space instance.

useMembers

The useMembers hook useful in building avatar stacks. Using useMembers hook you can retrieve spaces members.

useLocations

The useLocations hook lets you subscribe to location events. Location events are emitted whenever a member changes location.

useLocks

The useLocks hook lets you subscribe to lock events by registering a listener. Lock events are emitted whenever the lock state transitions into locked or unlocked.

useLock

The useLock returns the status of a lock and, if it has been acquired, the member holding the lock.

useCursors

The useCursors allows you to track a member’s pointer position updates across an application.

Spaces hooks are client-side oriented. If you employ server-side rendering, ensure components using these hooks render only on the client-side.

npm install ably @ably/spaces

Copy
Copied!

An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using token authentication.

Sign up to Ably to create an API key in the dashboard or use the Control API to create an API programmatically.

Use the SpacesProvider component to connect to Ably. The SpacesProvider should wrap every component that needs to access Spaces.

React
Select...

import { Realtime } from "ably";
import Spaces from "@ably/spaces";
import { SpacesProvider, SpaceProvider } from "@ably/spaces/react";


const ably = new Realtime.Promise({ key: "<loading API key, please wait>", clientId: 'clemons' });
const spaces = new Spaces(ably);


root.render(
  <SpacesProvider client={spaces}>
    <SpaceProvider name="my-space">
      <App />
    </SpaceProvider>
  </SpacesProvider>
)

API Key:
Demo Only
Copy
Copied!

The useSpace hook enables you to subscribe to the current Space, receive Space state events, and get the current Space instance.

React
Select...

const { space } = useSpace((update) => {
  console.log(update);
});

Copy
Copied!

useMembers is used to build avatar stacks. It retrieves members of the space, including members that have recently left the space, but have not yet been removed.

React
Select...

const { self, others, members } = useMembers();

Copy
Copied!

• self – a member’s own member object
• others – an array of member objects for all members other than the member themselves
• members – an array of all member objects, including the member themselves

useMembers also enables you to subscribe to members entering, leaving, and being removed from the Space (after a timeout), as well as when a member updates their profile information.

React
Select...

// Subscribe to all member events in a space
useMembers((memberUpdate) => {
  console.log(memberUpdate);
});


// Subscribe to member enter events only
useMembers('enter', (memberJoined) => {
  console.log(memberJoined);
});


// Subscribe to member leave events only
useMembers('leave', (memberLeft) => {
  console.log(memberLeft);
});


// Subscribe to member remove events only
useMembers('remove', (memberRemoved) => {
  console.log(memberRemoved);
});


// Subscribe to profile updates on members only
useMembers('updateProfile', (memberProfileUpdated) => {
  console.log(memberProfileUpdated);
});


// Subscribe to all updates to members
useMembers('update', (memberUpdate) => {
  console.log(memberUpdate);
});

Copy
Copied!

useLocations enables you to subscribe to location events. Location events are emitted whenever a member changes location.

React
Select...

useLocations((locationUpdate) => {
  console.log(locationUpdate);
});

Copy
Copied!

useLocations also enables you to update the current member location using the update method provided by the hook. For example:

React
Select...

const { update } = useLocations((locationUpdate) => {
  console.log(locationUpdate);
});

Copy
Copied!

useLocks enables you to subscribe to lock events by registering a listener. Lock events are emitted whenever a lock transitions into the locked or unlocked state.

React
Select...

useLocks((lockUpdate) => {
  console.log(lockUpdate);
});

Copy
Copied!

useLock returns the status of a lock and, if the lock has been acquired, the member holding that lock.

React
Select...

const { status, member } = useLock('my-lock');

Copy
Copied!

useCursors enables you to track a member’s cursor position and provide a view of all members’ cursors within a space. For example:

React
Select...

// Subscribe to events published on "mousemove" by all members
const { set } =  useCursors((cursorUpdate) => {
  console.log(cursorUpdate);
});


useEffect(() => {
  // Publish a your cursor position on "mousemove" including optional data
  const eventListener = ({ clientX, clientY }) => {
    set({ position: { x: clientX, y: clientY }, data: { color: 'red' } });
  }


  window.addEventListener('mousemove', eventListener);


  return () => {
    window.removeEventListener('mousemove', eventListener);
  };
});

Copy
Copied!

If you provide { returnCursors: true } as an option you can retrieve active members’ cursors:

React
Select...

const { cursors } =  useCursors((cursorUpdate) => {
  console.log(cursorUpdate);
}, { returnCursors: true });

Copy
Copied!

useSpace, useMembers, useLocks and useCursors return connection and channel errors you may encounter, so that you can handle then within your components. This may include when a client doesn’t have permission to attach to a channel, or if it loses its connection to Ably.

React
Select...

const { connectionError, channelError } = useMembers();


if (connectionError) {
  // TODO: handle connection errors
} else if (channelError) {
  // TODO: handle channel errors
} else {
  return <SpacesPoweredComponent />
}

Copy
Copied!