diff --git a/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx b/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx
index b0a50068181faa..c1c46f4f4c74f6 100644
--- a/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx
+++ b/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx
@@ -127,6 +127,38 @@ In `session` mode, this will upload any pending recording data to Sentry. In `bu
 
 Calling `flush()` while Session Replay is stopped will start a new session recording.
 
+## Listening to Lifecycle Events
+
+<AvailableSince version="10.50.0" />
+
+You can listen to replay lifecycle events on the Sentry client to know when recording starts and stops. This is useful for wrapper libraries or custom UIs that need to stay in sync with replay state.
+
+```javascript
+const client = Sentry.getClient();
+
+client.on('replayStart', ({ sessionId, recordingMode }) => {
+  // recordingMode: 'session' | 'buffer'
+  console.log(`Replay ${sessionId} started in ${recordingMode} mode`);
+});
+
+client.on('replayEnd', ({ sessionId, reason }) => {
+  // reason: 'manual' | 'sessionExpired' | 'sendError' | 'mutationLimit'
+  //       | 'eventBufferError' | 'eventBufferOverflow'
+  console.log(`Replay ${sessionId} ended: ${reason}`);
+});
+```
+
+The `replayEnd` hook includes a typed `reason` so you can distinguish calling `replay.stop()` yourself from an internal stop:
+
+| Reason | Description |
+|--------|-------------|
+| `manual` | You called `replay.stop()` |
+| `sessionExpired` | The session exceeded max duration or idle timeout |
+| `sendError` | The SDK failed to send recording data to Sentry |
+| `mutationLimit` | The DOM mutation limit was exceeded |
+| `eventBufferError` | The event buffer hit an internal error |
+| `eventBufferOverflow` | The event buffer exceeded its size limit |
+
 ## Examples of Custom Sampling
 
 There are ways to enable custom sampling if you're interested in tracking a particular action or group, for example, a specific segment of users or a problematic URL.