Providers

The Ably Chat React SDK provides two context providers that supply chat functionality to your component tree. All chat hooks must be used within these providers.

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 JWT authentication. Authenticate an Ably.Realtime Pub/Sub client and then pass it to the ChatClientProvider.

import * as Ably from 'ably';
import { ChatClient } from '@ably/chat';
import { ChatClientProvider, ChatRoomProvider } from '@ably/chat/react';

const realtimeClient = new Ably.Realtime({ key: 'demokey:*****', clientId: 'my-client-id' });
const chatClient = new ChatClient(realtimeClient);

function App() {
  return (
    <ChatClientProvider client={chatClient}>
      <ChatRoomProvider name="my-room">
        {/* Chat hooks can be used here */}
      </ChatRoomProvider>
    </ChatClientProvider>
  );
}

ChatClientProvider

Provides a ChatClient instance to all descendant components via React context. All chat hooks, including useChatClient and useChatConnection, require this provider to be present in the component tree.

The client property should be memoized to prevent unnecessary context updates. The provider manages room reference counting internally, only detaching rooms when no references remain.

Properties

ChatRoomProvider

Provides room context to descendant components. All room-level hooks such as useMessages, usePresence, and useTyping require this provider.

The provider automatically handles room attachment and detachment. Multiple providers for the same room with the same options share the same underlying room instance through reference counting.

Properties

ErrorInfo

A standardized, generic Ably error object that contains an Ably-specific status code, and a generic HTTP status code. All errors returned from Ably are compatible with the ErrorInfo structure.

DiscontinuityListener

A callback to detect and respond to discontinuities in the event stream. Discontinuities occur when the client may have missed events due to connectivity issues.

Example

import * as Ably from 'ably';
import { ChatClient } from '@ably/chat';
import { ChatClientProvider, ChatRoomProvider } from '@ably/chat/react';
import { useMemo } from 'react';

// Create clients outside of components
// Use JWT token authentication in production
const realtimeClient = new Ably.Realtime({
  key: 'demokey:*****',
  clientId: 'user-123'
});
const chatClient = new ChatClient(realtimeClient);

function App() {
  // Memoize room options to prevent unnecessary recreations
  const roomOptions = useMemo(() => ({
    typing: { heartbeatThrottleMs: 5000 },
    occupancy: { enableEvents: true },
  }), []);

  return (
    <ChatClientProvider client={chatClient}>
      <ChatRoomProvider name="my-room" options={roomOptions}>
        <ChatRoom />
      </ChatRoomProvider>
    </ChatClientProvider>
  );
}

function ChatRoom() {
  // All chat hooks can be used here
  return <div>Chat room content</div>;
}