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:
| Hook | Description |
|---|---|
useSpace | The useSpace hook lets you subscribe to the current Space, receive Space state events, and get the current Space instance. |
useMembers | The useMembers hook is useful in building avatar stacks. Using useMembers, you can retrieve space 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 hook returns the status of a lock and, if it has been acquired, the member holding the lock. |
useCursors | The useCursors hook 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.
Install
npm install ably @ably/spacesAuthenticate
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.
Usage
Setting up the Spaces Provider
Use the SpacesProvider component to connect to Ably. The SpacesProvider should wrap every component that needs to access Spaces.
useSpace
The useSpace hook enables you to subscribe to the current Space, receive Space state events, and get the current Space instance.
useMembers
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.
self- a member’s own member objectothers- an array of member objects for all members other than the member themselvesmembers- 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.
useLocations
useLocations enables you to subscribe to location events. Location events are emitted whenever a member changes location.
useLocations also enables you to update the current member location using the update method provided by the hook. For example:
useLocks
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.
useLock
useLock returns the status of a lock and, if the lock has been acquired, the member holding that lock.
useCursors
useCursors enables you to track a member's cursor position and provide a view of all members' cursors within a space. For example:
If you provide { returnCursors: true } as an option you can retrieve active members' cursors:
Error handling
useSpace, useMembers, useLocks, and useCursors return connection and channel errors you may encounter, so that you can handle them 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.