+```react
+import * as Ably from 'ably';
+import { ChatClient } from '@ably/chat';
+import { ChatClientProvider, ChatRoomProvider } from '@ably/chat/react';
+
+const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: 'my-client-id' });
+const chatClient = new ChatClient(realtimeClient);
+
+function App() {
+ return (
+
+
+ {/* Chat hooks can be used here */}
+
+
+ );
+}
+```
+
+
+
+
+## ChatClientProvider
+
+Provides a `ChatClient` instance to all descendant components via React context. All chat hooks, including [`useChatClient`](/docs/chat/api/react/use-chat-client) and [`useChatConnection`](/docs/chat/api/react/use-chat-connection), 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
+
+
+```react
+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
+const realtimeClient = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ 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 (
+
+
+
+
+ );
+}
+
+function ChatRoom() {
+ // All chat hooks can be used here
+ return Chat room content;
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-chat-client.mdx b/src/pages/docs/chat/api/react/use-chat-client.mdx
new file mode 100644
index 0000000000..723c742ff1
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-chat-client.mdx
@@ -0,0 +1,56 @@
+---
+title: useChatClient
+meta_description: "API reference for the useChatClient hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useChatClient, hooks, chat client, clientId"
+---
+
+The `useChatClient` hook provides access to the `ChatClient` instance supplied by the [`ChatClientProvider`](/docs/chat/api/react/providers#chatClientProvider). It automatically monitors the `clientId` and refreshes when connection state changes.
+
+
+```react
+import { useChatClient } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { clientId } = useChatClient();
+ return Connected as: {clientId}
;
+};
+```
+
+
+This hook must be used within a [`ChatClientProvider`](/docs/chat/api/react/providers#chatClientProvider).
+
+## Returns
+
+The `useChatClient` hook returns an object with the following properties:
+
+
+```react
+import { useChatClient, useChatConnection } from '@ably/chat/react';
+
+function UserStatus() {
+ const { clientId } = useChatClient();
+ const { currentStatus } = useChatConnection();
+
+ if (!clientId) {
+ return Connecting...
;
+ }
+
+ return (
+
+ Logged in as: {clientId}
+ Connection status: {currentStatus}
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-chat-connection.mdx b/src/pages/docs/chat/api/react/use-chat-connection.mdx
new file mode 100644
index 0000000000..921504269e
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-chat-connection.mdx
@@ -0,0 +1,108 @@
+---
+title: useChatConnection
+meta_description: "API reference for the useChatConnection hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useChatConnection, hooks, connection status, ConnectionStatus"
+---
+
+The `useChatConnection` hook provides the current connection status and error state between the client and Ably. It supports listener callbacks for status changes and automatically cleans up listeners on component unmount.
+
+
+```react
+import { useChatConnection } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { currentStatus, error } = useChatConnection();
+ return Connection: {currentStatus}
;
+};
+```
+
+
+This hook must be used within a [`ChatClientProvider`](/docs/chat/api/react/providers#chatClientProvider).
+
+## Parameters
+
+The `useChatConnection` hook accepts an optional configuration object:
+
+
+```react
+import { ConnectionStatus } from '@ably/chat';
+import { useChatConnection } from '@ably/chat/react';
+
+function ConnectionIndicator() {
+ const { currentStatus, error } = useChatConnection({
+ onStatusChange: (change) => {
+ console.log('Status changed from', change.previous, 'to', change.current);
+ if (change.retryIn) {
+ console.log('Retrying in', change.retryIn, 'ms');
+ }
+ },
+ });
+
+ return (
+
+
+ {currentStatus}
+
+ {error && Error: {error.message}
}
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-messages.mdx b/src/pages/docs/chat/api/react/use-messages.mdx
new file mode 100644
index 0000000000..56b427a022
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-messages.mdx
@@ -0,0 +1,628 @@
+---
+title: useMessages
+meta_description: "API reference for the useMessages hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useMessages, hooks, messages, send, history, update, delete, reactions"
+---
+
+The `useMessages` hook provides access to message operations within a chat room, including sending, retrieving, updating, and deleting messages, as well as managing message reactions. When a listener is supplied, the hook automatically subscribes to new messages.
+
+
+```react
+import { useMessages } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { sendMessage, history } = useMessages({
+ listener: (event) => {
+ console.log('New message:', event.message.text);
+ },
+ });
+
+ return ;
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+## Parameters
+
+The `useMessages` hook accepts an optional configuration object:
+
+
+```react
+import { ChatMessageEventType, OrderBy, MessageReactionType } from '@ably/chat';
+import { useMessages } from '@ably/chat/react';
+import { useState, useCallback } from 'react';
+
+function ChatMessages() {
+ const [messages, setMessages] = useState([]);
+
+ const { sendMessage, updateMessage, deleteMessage, history, sendReaction } = useMessages({
+ listener: (event) => {
+ setMessages((prev) => {
+ switch (event.type) {
+ case ChatMessageEventType.Created:
+ return [...prev, event.message];
+ case ChatMessageEventType.Updated:
+ case ChatMessageEventType.Deleted:
+ return prev.map((msg) =>
+ msg.serial === event.message.serial ? event.message : msg
+ );
+ default:
+ return prev;
+ }
+ });
+ },
+ reactionsListener: (event) => {
+ setMessages((prev) =>
+ prev.map((msg) =>
+ msg.serial === event.messageSerial
+ ? msg.with(event)
+ : msg
+ )
+ );
+ },
+ });
+
+ const loadHistory = useCallback(async () => {
+ const result = await history({ limit: 50, orderBy: OrderBy.OldestFirst });
+ setMessages(result.items);
+ }, [history]);
+
+ const handleSend = useCallback(async (text) => {
+ await sendMessage({ text });
+ }, [sendMessage]);
+
+ const handleReact = useCallback(async (serial, emoji) => {
+ await sendReaction(serial, { name: emoji, type: MessageReactionType.Distinct });
+ }, [sendReaction]);
+
+ return (
+
+
+ {messages.map((msg) => (
+
+ {msg.clientId}: {msg.text}
+
+
+
+ ))}
+
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-occupancy.mdx b/src/pages/docs/chat/api/react/use-occupancy.mdx
new file mode 100644
index 0000000000..41475d8ff3
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-occupancy.mdx
@@ -0,0 +1,109 @@
+---
+title: useOccupancy
+meta_description: "API reference for the useOccupancy hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useOccupancy, hooks, occupancy, connections, presence members, user count"
+---
+
+The `useOccupancy` hook provides realtime room occupancy information, automatically tracking the number of connections and presence members in a room.
+
+
+```react
+import { useOccupancy } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { connections, presenceMembers } = useOccupancy();
+ return {connections} connections, {presenceMembers} present
;
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+## Parameters
+
+The `useOccupancy` hook accepts an optional configuration object:
+
+
+```react
+import { useOccupancy } from '@ably/chat/react';
+
+function ViewerCount() {
+ const { connections, presenceMembers } = useOccupancy({
+ listener: (event) => {
+ console.log('Occupancy updated:', event.occupancy);
+ },
+ });
+
+ return (
+
+ {connections} watching
+ {presenceMembers} in chat
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-presence-listener.mdx b/src/pages/docs/chat/api/react/use-presence-listener.mdx
new file mode 100644
index 0000000000..5eb398457c
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-presence-listener.mdx
@@ -0,0 +1,153 @@
+---
+title: usePresenceListener
+meta_description: "API reference for the usePresenceListener hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, usePresenceListener, hooks, presence, members, online users, subscribe"
+---
+
+The `usePresenceListener` hook provides live presence information for all users in a room. It automatically subscribes to presence events and maintains an up-to-date roster of presence members. Use [`usePresence`](/docs/chat/api/react/use-presence) to manage the current user's own presence state.
+
+
+```react
+import { usePresenceListener } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { presenceData } = usePresenceListener();
+
+ return (
+
+ {presenceData.map((member) => (
+ - {member.clientId}
+ ))}
+
+ );
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+## Parameters
+
+The `usePresenceListener` hook accepts an optional configuration object:
+
+
+```react
+import { PresenceEventType } from '@ably/chat';
+import { usePresenceListener } from '@ably/chat/react';
+
+function OnlineUsers() {
+ const { presenceData, error } = usePresenceListener({
+ listener: (event) => {
+ switch (event.type) {
+ case PresenceEventType.Enter:
+ console.log(`${event.member.clientId} joined`);
+ break;
+ case PresenceEventType.Leave:
+ console.log(`${event.member.clientId} left`);
+ break;
+ case PresenceEventType.Update:
+ console.log(`${event.member.clientId} updated their status`);
+ break;
+ }
+ },
+ });
+
+ if (error) {
+ return Error loading presence: {error.message}
;
+ }
+
+ return (
+
+ Online ({presenceData.length})
+
+ {presenceData.map((member) => (
+ -
+ {member.clientId}
+ {member.data?.status && ` (${member.data.status})`}
+
+ ))}
+
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-presence.mdx b/src/pages/docs/chat/api/react/use-presence.mdx
new file mode 100644
index 0000000000..1c6922d0dd
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-presence.mdx
@@ -0,0 +1,172 @@
+---
+title: usePresence
+meta_description: "API reference for the usePresence hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, usePresence, hooks, presence, enter, leave, update, online users"
+---
+
+The `usePresence` hook manages the current user's presence in a chat room. By default, it automatically enters presence on mount and leaves on unmount. Use [`usePresenceListener`](/docs/chat/api/react/use-presence-listener) to observe the presence state of all users.
+
+
+```react
+import { usePresence } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { update, myPresenceState } = usePresence();
+
+ return (
+
+ Present: {myPresenceState.present ? 'Yes' : 'No'}
+
+
+ );
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+
+
+## Parameters
+
+The `usePresence` hook accepts an optional configuration object:
+
+
+```react
+import { usePresence } from '@ably/chat/react';
+
+function PresenceControls() {
+ const { enter, leave, update, myPresenceState } = usePresence({
+ initialData: { status: 'online', nickname: 'Alice' },
+ });
+
+ return (
+
+ Status: {myPresenceState.present ? 'Online' : 'Offline'}
+ {myPresenceState.error && Error: {myPresenceState.error.message}
}
+
+
+
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-room-reactions.mdx b/src/pages/docs/chat/api/react/use-room-reactions.mdx
new file mode 100644
index 0000000000..5b17495479
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-room-reactions.mdx
@@ -0,0 +1,169 @@
+---
+title: useRoomReactions
+meta_description: "API reference for the useRoomReactions hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useRoomReactions, hooks, room reactions, ephemeral reactions, emoji"
+---
+
+The `useRoomReactions` hook enables sending and subscribing to ephemeral room-level reactions. Room reactions are commonly used for live interactions like floating emojis, applause, or other realtime audience feedback. Unlike message reactions, room reactions are not persisted.
+
+
+```react
+import { useRoomReactions } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { sendRoomReaction } = useRoomReactions({
+ listener: (event) => {
+ console.log(`${event.reaction.clientId} reacted with ${event.reaction.name}`);
+ },
+ });
+
+ return ;
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+## Parameters
+
+The `useRoomReactions` hook accepts an optional configuration object:
+
+
+```react
+import { useRoomReactions } from '@ably/chat/react';
+import { useState, useCallback } from 'react';
+
+function ReactionBar() {
+ const [recentReactions, setRecentReactions] = useState([]);
+
+ const { sendRoomReaction } = useRoomReactions({
+ listener: (event) => {
+ const { reaction } = event;
+ setRecentReactions((prev) => [
+ ...prev.slice(-9),
+ { name: reaction.name, clientId: reaction.clientId, isSelf: reaction.isSelf },
+ ]);
+ },
+ });
+
+ const emojis = ['👍', '❤️', '😂', '🎉', '👏'];
+
+ return (
+
+
+ {emojis.map((emoji) => (
+
+ ))}
+
+
+ {recentReactions.map((r, i) => (
+ {r.name}
+ ))}
+
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-room.mdx b/src/pages/docs/chat/api/react/use-room.mdx
new file mode 100644
index 0000000000..4a095f97d6
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-room.mdx
@@ -0,0 +1,141 @@
+---
+title: useRoom
+meta_description: "API reference for the useRoom hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useRoom, hooks, room, attach, detach, RoomStatus"
+---
+
+The `useRoom` hook provides access to room information and basic room operations such as manually attaching and detaching.
+
+
+```react
+import { useRoom } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { roomName, roomStatus } = useRoom();
+ return Room: {roomName} ({roomStatus})
;
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+
+
+## Parameters
+
+The `useRoom` hook accepts an optional configuration object:
+
+
+```react
+import { RoomStatus } from '@ably/chat';
+import { useRoom } from '@ably/chat/react';
+
+function RoomHeader() {
+ const { roomName, roomStatus, roomError } = useRoom({
+ onStatusChange: (change) => {
+ console.log(`Room status: ${change.previous} -> ${change.current}`);
+ },
+ });
+
+ return (
+
+ {roomName}
+ {roomStatus}
+ {roomStatus === RoomStatus.Failed && roomError && (
+ Error: {roomError.message}
+ )}
+
+ );
+}
+```
+
diff --git a/src/pages/docs/chat/api/react/use-typing.mdx b/src/pages/docs/chat/api/react/use-typing.mdx
new file mode 100644
index 0000000000..e70ae5bf99
--- /dev/null
+++ b/src/pages/docs/chat/api/react/use-typing.mdx
@@ -0,0 +1,196 @@
+---
+title: useTyping
+meta_description: "API reference for the useTyping hook in the Ably Chat React SDK."
+meta_keywords: "Ably Chat SDK, React, useTyping, hooks, typing indicators, keystroke, stop"
+---
+
+The `useTyping` hook manages typing indicator state for a chat room, automatically tracking users who are currently typing and updating state in realtime.
+
+
+```react
+import { useTyping } from '@ably/chat/react';
+
+const MyComponent = () => {
+ const { keystroke, stop, currentTypers } = useTyping();
+
+ return (
+
+ {currentTypers.length > 0 && (
+ {currentTypers.map(t => t.clientId).join(', ')} typing...
+ )}
+ keystroke()}
+ onBlur={() => stop()}
+ />
+
+ );
+};
+```
+
+
+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+## Parameters
+
+The `useTyping` hook accepts an optional configuration object:
+
+
+```react
+import { useTyping } from '@ably/chat/react';
+import { useState, useCallback } from 'react';
+
+function MessageInput({ onSend }) {
+ const [text, setText] = useState('');
+ const { keystroke, stop, currentTypers } = useTyping({
+ listener: (event) => {
+ const { change } = event;
+ if (change.type === 'typing.started') {
+ console.log(`${change.clientId} started typing`);
+ }
+ },
+ });
+
+ const handleInput = useCallback((e) => {
+ setText(e.target.value);
+ if (e.target.value.length > 0) {
+ keystroke();
+ } else {
+ stop();
+ }
+ }, [keystroke, stop]);
+
+ const handleSubmit = useCallback(async () => {
+ await onSend(text);
+ setText('');
+ await stop();
+ }, [text, onSend, stop]);
+
+ return (
+
+ {currentTypers.length > 0 && (
+
+ {currentTypers.length === 1
+ ? `${currentTypers[0].clientId} is typing...`
+ : `${currentTypers.map(t => t.clientId).join(', ')} are typing...`}
+
+ )}
+ stop()} />
+
+
+ );
+}
+```
+