- 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
| 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. |
Install
Authenticate
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 theSpacesProvider component to connect to Ably. The SpacesProvider should wrap every component that needs to access Spaces.
useSpace
TheuseSpace 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.