React Hooks

Leverage the power of Ably in your React applications using idiomatic, easy-to-use React Hooks. This package enables you to:

  • Subscribe to messages on Ably channels.
  • Publish messages using the channel instances provided by hooks.
  • Subscribe to presence updates on channels.
  • Trigger presence updates.

The following hooks are available:

useChannel
The useChannel hook subscribes to a channel and receives messages from it.
usePresence
The usePresence hook subscribes to presence events on a channel, notifying when users join or leave the channel.
useConnectionStateListener
The useConnectionStateListener hook attaches a listener to be notified of connection state changes in the Ably client.
useChannelStateListener
The useChannelStateListener hook attaches a listener to be notified of channel state changes.
useAbly
The useAbly hook grants access to the Ably client instance provided by the AblyProvider context.

All hooks manage the lifecycle of Ably SDK instances for you, ensuring that you subscribe and unsubscribe to channels and events when your React components re-render.

Ably JavaScript SDK versions >= 1.2.44 include React Hook functionality as standard. You don’t need to install any additional packages.

npm install --save ably
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 AblyProvider component to connect to Ably. This component should be placed high up in your component tree, wrapping every component that needs to access Ably.

You can create your own client and pass it to the context provider:

Select...
import { Realtime } from 'ably'; import { AblyProvider } from 'ably/react'; const client = new Realtime({ key: '<API-key>', clientId: '<client-ID>' }); root.render( <AblyProvider client={client}> <App /> </AblyProvider> );
Copied!

If you need to use multiple Ably clients on the same page, you can keep your clients in separate AblyProvider components. If nesting AblyProviders, you can pass a string ID for each client as a property to the provider.

Select...
root.render( <AblyProvider client={client} id={'providerOne'}> <AblyProvider client={client} id={'providerTwo'}> <App /> </AblyProvider> </AblyProvider> );
Copied!

The useChannel hook enables you to subscribe to a channel and receive its messages. It can be combined with the React useState hook to maintain a list of messages in your app state.

Select...
const [messages, updateMessages] = useState([]); const { channel } = useChannel('channelName', (message) => { updateMessages((prev) => [...prev, message]); });
Copied!

You can also filter messages by providing a message name to the useChannel function:

Select...
const { channel } = useChannel('channelName', 'messageName', (message) => { console.log(message); });
Copied!

The usePresence hook enables you to subscribe to presence events on a channel, notifying you when a user enters or leaves the presence set or updates their member data.

Select...
const { presenceData, updateStatus } = usePresence('channelName', 'initialPresenceStatus'); // Convert presence data to list items to render const peers = presenceData.map((msg, index) => <li key={index}>{msg.clientId}: {msg.data}</li>); // The `updateStatus` function can be used to update the presence data for the current client updateStatus('newStatus');
Copied!

The useConnectionStateListener hook enables you to attach a listener to be notified of connection state changes. This can be useful for detecting when a client has lost its connection.

Select...
useConnectionStateListener((stateChange) => { console.log(stateChange.current); // the new connection state console.log(stateChange.previous); // the previous connection state console.log(stateChange.reason); // if applicable, an error indicating the reason for the connection state change });
Copied!

You can also pass a filter to only listen for specific connection states:

Select...
useConnectionStateListener('failed', listener); // the listener only gets called when the connection state becomes failed useConnectionStateListener(['failed', 'suspended'], listener); // the listener only gets called when the connection state becomes failed or suspended
Copied!

The useChannelStateListener hook enables you to attach a listener to be notified of channel state changes. This can be useful for detecting when a channel error has occurred.

Select...
useChannelStateListener((stateChange) => { console.log(stateChange.current); // the new channel state console.log(stateChange.previous); // the previous channel state console.log(stateChange.reason); // if applicable, an error indicating the reason for the channel state change });
Copied!

Similar to useConnectionStateListener, you can also pass in a filter to only listen to specific channel states:

Select...
useChannelStateListener('failed', listener); // the listener only gets called when the channel state becomes failed useChannelStateListener(['failed', 'suspended'], listener); // the listener only gets called when the channel state becomes failed or suspended
Copied!

The useAbly hook enables access to the Ably client used by the AblyProvider context. This can be used to access APIs which aren’t available through the React Hooks submodule.

Select...
const client = useAbly(); client.authorize();
Copied!

When using Ably React Hooks, you may encounter errors. The useChannel and usePresence hooks return connection and channel errors, enabling you to handle them in your components.

Select...
const { connectionError, channelError } = useChannel('channelName', messageHandler);
Copied!
Install
v1.2