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

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 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 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.

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.