[DX-629] Add Chat React API references by m-hulbert · Pull Request #3272 · ably/docs

m-hulbert · 2026-03-12T19:25:58Z

Description

This PR adds an API reference for Chat in React using the new NestedTable and MethodSignature components. It should have parity with the TypeDoc references.

There is 1 commit per file, however I haven't yet updated the references in the conceptual content to point to these references yet to keep this PR smaller for review feedback. I will add that as a final commit once we are happy with this content.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

coderabbitai · 2026-03-12T19:26:34Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0733a5aa-1dce-4525-acc8-64a9d14fe914

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch dx-629-chat-react-api-refs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

splindsay-92

Just a few things so far, but mostly looks good!

src/pages/docs/chat/api/react/providers.mdx

src/pages/docs/chat/api/react/use-messages.mdx

splindsay-92 · 2026-03-26T15:06:53Z

src/pages/docs/chat/api/react/providers.mdx

+
+// Create clients outside of components
+const realtimeClient = new Ably.Realtime({
+  key: '{{API_KEY}}',


Worth adding a short comment like // Use JTW token authentication in production?

splindsay-92 · 2026-03-26T15:14:05Z

src/pages/docs/chat/api/react/use-messages.mdx

+    },
+  });
+
+  return <button onClick={() => sendMessage({ text: 'Hello!' })}>Send</button>;


Since sendMessage is async, the more correct way to do this would be define a handler to capture any error state. E.g.

const handleSend = () => { sendMessage().catch((error: unknown) => { console.error('Failed to send message', error); }); };

The above still works fine though, and errors would still be logged as SDK logs regardless (so you'd see them in the console), so I'll defer to you on if you think this really needs to be that verbose or if the simplicity is better and gets the job done here :)

splindsay-92 · 2026-03-26T15:18:39Z

src/pages/docs/chat/api/react/use-messages.mdx

+function ChatMessages() {
+  const [messages, setMessages] = useState([]);
+
+  const { sendMessage, updateMessage, deleteMessage, history, sendReaction } = useMessages({


Just my opinion, but historyBeforeSubscribe is preferable over history, but again, it's not incorrect :)

splindsay-92 · 2026-03-26T15:23:54Z

src/pages/docs/chat/api/react/use-messages.mdx

+          case ChatMessageEventType.Updated:
+          case ChatMessageEventType.Deleted:
+            return prev.map((msg) =>
+              msg.serial === event.message.serial ? event.message : msg


This should really be checking the version serial before doing any sort of swap. Also, we have the .with() function on a message to make this very easy too :)
msg.serial === event.message.serial ? msg.with(event.message) : msg

splindsay-92 · 2026-03-26T15:45:06Z

src/pages/docs/chat/api/react/use-chat-client.mdx

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


This isn't really the case, it provides access to only the clientId, not the instance itself.

splindsay-92 · 2026-03-26T15:59:37Z

src/pages/docs/chat/api/react/use-room-reactions.mdx

+| Property | Required | Description | Type |
+| --- | --- | --- | --- |
+| name | Required | The name of the reaction, typically an emoji or identifier. | String |
+| metadata | Optional | Additional metadata to include with the reaction. | JsonObject |


splindsay-92 · 2026-03-26T15:59:52Z

src/pages/docs/chat/api/react/use-room-reactions.mdx

+| --- | --- | --- | --- |
+| name | Required | The name of the reaction, typically an emoji or identifier. | String |
+| metadata | Optional | Additional metadata to include with the reaction. | JsonObject |
+| headers | Optional | Additional information in Ably message extras, usable for features like referencing external resources. | Headers |


splindsay-92 · 2026-03-26T16:01:36Z

src/pages/docs/chat/api/react/use-presence-listener.mdx

+| connectionId | The connection ID of the present user. | String |
+| data | The presence data associated with the user. | <Table id='PresenceData'/> or Undefined |
+| extras | Additional data included with the presence message. | JsonObject or Undefined |
+| updatedAt | When this presence state was last updated. | Date |


encoding should also be mentioned here I think

splindsay-92 · 2026-03-26T16:02:29Z

src/pages/docs/chat/api/react/use-presence.mdx

+This hook must be used within a [`ChatRoomProvider`](/docs/chat/api/react/providers#chatRoomProvider).
+
+<Aside data-type='important'>
+Avoid using multiple instances of this hook within the same `ChatClientProvider`, as they share the same underlying presence instance.


Suggested change

Avoid using multiple instances of this hook within the same `ChatClientProvider`, as they share the same underlying presence instance.

Avoid using multiple instances of this hook within the same `ChatRoomProvider`, as they share the same underlying presence instance.

splindsay-92 · 2026-03-26T16:04:47Z

src/pages/docs/chat/api/react/use-typing.mdx

+
+</Table>
+
+<Table id='TypingChange' hidden>


There isn't a TypingChange event, but the properties here exist on the change field of the TypingSetEvent, is that what's meant?

m-hulbert and others added 12 commits March 12, 2026 19:24

Add Providers API reference for Chat React SDK

b322c57

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useChatClient hook API reference

3b201ad

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useChatConnection hook API reference

dec57f9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useRoom hook API reference

087105a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useMessages hook API reference

73cfb2d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add usePresence hook API reference

b0e001b

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add usePresenceListener hook API reference

0bfa6f2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useOccupancy hook API reference

872091e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useTyping hook API reference

7bce2cb

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add useRoomReactions hook API reference

b748739

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add React hooks section to Chat navigation

e9feb4e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update Chat API index to link to React hook references

15ddaf8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

m-hulbert self-assigned this Mar 12, 2026

m-hulbert added the review-app Create a Heroku review app label Mar 12, 2026

ably-ci temporarily deployed to ably-docs-dx-629-chat-r-bl9cry March 12, 2026 19:26 Inactive

m-hulbert requested a review from splindsay-92 March 13, 2026 08:50

splindsay-92 reviewed Mar 14, 2026

View reviewed changes

m-hulbert added 2 commits March 17, 2026 18:28

fixup! Add Providers API reference for Chat React SDK

797ae27

fixup! Add useMessages hook API reference

ff16353

m-hulbert temporarily deployed to ably-docs-dx-629-chat-r-bl9cry March 17, 2026 18:29 Inactive

fix: update ErrorInfo.cause to type ErrorInfo in chat JS refs

a8b18c3

m-hulbert temporarily deployed to ably-docs-dx-629-chat-r-bl9cry March 17, 2026 18:30 Inactive

m-hulbert requested a review from splindsay-92 March 17, 2026 18:32

splindsay-92 reviewed Mar 19, 2026

View reviewed changes

src/pages/docs/chat/api/react/use-messages.mdx Show resolved Hide resolved

m-hulbert added 2 commits March 24, 2026 16:33

fix: add clipped property to Chat JS API refs on message summaries

b15e2f4

fixup! Add useMessages hook API reference

fb8ba73

m-hulbert requested a review from splindsay-92 March 24, 2026 16:35

splindsay-92 reviewed Mar 26, 2026

View reviewed changes

	\| metadata \| Optional \| Additional metadata to include with the reaction. \| JsonObject \|
	\| metadata \| Optional \| Additional metadata to include with the reaction. \| RoomReactionMetadata \|

	\| headers \| Optional \| Additional information in Ably message extras, usable for features like referencing external resources. \| Headers \|
	\| headers \| Optional \| Additional information in Ably message extras, usable for features like referencing external resources. \| RoomReactionHeaders \|

	Avoid using multiple instances of this hook within the same `ChatClientProvider`, as they share the same underlying presence instance.
	Avoid using multiple instances of this hook within the same `ChatRoomProvider`, as they share the same underlying presence instance.

Conversation

m-hulbert commented Mar 12, 2026

Description

Checklist

Uh oh!

coderabbitai bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

splindsay-92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Mar 12, 2026 •

edited

Loading