From f9059427abaa2984032e9cee28cf7c3ade3eadee Mon Sep 17 00:00:00 2001
From: Ben <30612894+BenHavis@users.noreply.github.com>
Date: Sun, 30 Nov 2025 19:52:51 -0500
Subject: [PATCH] docs: add explanation of Realtime Broadcast usage in Realtime
 Chat (#40882)

Adds a section explaining that Realtime Chat uses Realtime Broadcast, does not
store messages by default, and relies on onMessage for persistence. Improves
developer understanding of expected behavior.
---
 .../content/docs/nextjs/realtime-chat.mdx           | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/apps/ui-library/content/docs/nextjs/realtime-chat.mdx b/apps/ui-library/content/docs/nextjs/realtime-chat.mdx
index 3010a19f553..7612c3c3204 100644
--- a/apps/ui-library/content/docs/nextjs/realtime-chat.mdx
+++ b/apps/ui-library/content/docs/nextjs/realtime-chat.mdx
@@ -20,6 +20,19 @@ description: Real-time chat component for collaborative applications
 
 The Realtime Chat component provides a complete chat interface that enables users to exchange messages in real-time within a shared room.
 
+## How it works under the hood
+
+This chat component uses **Supabase Realtime Broadcast** to send and receive messages between connected clients.
+
+Messages sent through Broadcast are:
+
+- delivered in real time to other connected clients
+- **not stored** unless you handle persistence yourself
+- **not guaranteed** to arrive if the client disconnects
+- scoped to a specific `roomName`, which corresponds to a broadcast channel
+
+This design keeps latency extremely low, but it means you should use the `onMessage` callback if you want to store messages permanently or show chat history on page load.
+
 ## Usage
 
 ### Basic usage