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.
- Enter the presence set on channels.
- Subscribe to presence updates on channels.
- Trigger presence updates.
The following hooks are available:
- useChannel
- The
useChannelhook subscribes to a channel and receives messages from it. - usePresence
- The
usePresencehook enters clients into the presence set. - usePresenceListener
- The
usePresenceListenerhook subscribes to presence events on a channel. - useConnectionStateListener
- The
useConnectionStateListenerhook attaches a listener to be notified of connection state changes in the Ably client. - useChannelStateListener
- The
useChannelStateListenerhook attaches a listener to be notified of channel state changes. - useAbly
- The
useAblyhook 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.
Install
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
CopyCopied!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 Ably Provider
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:
import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { createRoot } from 'react-dom/client';
const container = document.getElementById('root')!;
const root = createRoot(container);
const client = new Ably.Realtime({ key: '<API-key>', clientId: '<client-ID>' });
root.render(
<AblyProvider client={client}>
<App />
</AblyProvider>
);
CopyCopied!Multiple clients
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.
root.render(
<AblyProvider client={client} ablyId={'providerOne'}>
<AblyProvider client={client} ablyId={'providerTwo'}>
<App />
</AblyProvider>
</AblyProvider>
);
CopyCopied!Channel Provider
Use the ChannelProvider to define the channels you want to use in other hooks.
<ChannelProvider channelName="gum-box-eye">
<Component />
</ChannelProvider>
CopyCopied!You can also set channel options in the ChannelProvider component:
The following is an example of setting the rewind channel option:
<ChannelProvider channelName="gum-box-eye" options={{ params: { rewind: '1' } }}>
<Component />
</ChannelProvider>
CopyCopied!Use deriveOptions to set a subscription filter and only receive messages that satisfy a filter expression:
const deriveOptions = { filter: 'headers.email == `"[email protected]"` || headers.company == `"domain"`' }
return (
<ChannelProvider channelName="gum-box-eye" options={{ ... }} deriveOptions={deriveOptions}>
<Component />
</ChannelProvider>
)
CopyCopied!useChannel
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.
const [messages, updateMessages] = useState([]);
const { channel } = useChannel('gum-box-eye', (message) => {
updateMessages((prev) => [...prev, message]);
});
CopyCopied!You can also filter messages by providing a message name to the useChannel function:
const { channel } = useChannel('gum-box-eye', 'messageName', (message) => {
console.log(message);
});
CopyCopied!Use the publish function to publish messages to the channel:
const { publish } = useChannel("gum-box-eye")
publish("test-message", { text: "message text" });
CopyCopied!usePresence
The usePresence hook enables you to enter the presence set.
const { updateStatus } = usePresence('gum-box-eye');
// Optionally pass a second argument to 'usePresence' to set a client's initial member data
const { updateStatus } = usePresence('gum-box-eye', 'initialStatus');
// The `updateStatus` function can be used to update the presence data for the current client
updateStatus('newStatus');
CopyCopied!usePresenceListener
The usePresenceListener 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.
const { presenceData } = usePresenceListener('gum-box-eye');
// Convert presence data to list items to render
const peers = presenceData.map((msg, index) => <li key={index}>{msg.clientId}: {msg.data}</li>);
CopyCopied!useConnectionStateListener
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.
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
});
CopyCopied!You can also pass a filter to only listen for specific connection states:
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
CopyCopied!useChannelStateListener
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.
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
});
CopyCopied!Similar to useConnectionStateListener, you can also pass in a filter to only listen to specific channel states:
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
CopyCopied!useAbly
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.
const client = useAbly();
client.authorize();
CopyCopied!Error handling
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.
const { connectionError, channelError } = useChannel('gum-box-eye', messageHandler);
CopyCopied!