# rrweb: Replayer API
URL: https://generaltranslation.com/en-US/docs/rrweb/reference/replayer.mdx
---

title: Replayer API
description: Play an rrweb bundle with localized text overlays and playback controls. Reference for the gt-rrweb replayer API.

---

Import replayer values from `gt-rrweb/replay`. The framework-agnostic player requires the optional `@rrweb/replay` peer dependency, and the React wrapper also requires React 18 or later.

## Overview [#overview]

| API | Description |
| --- | --- |
| [`createGTReplayer`](#create-gt-replayer) | Mounts a player into a DOM element. |
| [`GTReplayer`](#gt-replayer) | React wrapper around `createGTReplayer`. |
| [`GTReplayerBundle`](#replayer-bundle) | Event stream and optional locale data. |
| [`GTReplayerOptions`](#replayer-options) | Initial locale, switching, and debug options. |
| [`GTReplayerHandle`](#replayer-handle) | Destroys a mounted player. |

## `createGTReplayer` [#create-gt-replayer]

```ts
function createGTReplayer(
  container: HTMLElement,
  bundle: GTReplayerBundle,
  options?: GTReplayerOptions
): GTReplayerHandle;
```

The function mounts a self-contained player and starts playback. It includes a letterboxed stage, click-based cursor, scrubber, light and dark theme control, full-screen control, and locale switcher when the bundle supports it.

The container should be sized by its parent. Call `destroy()` before removing or reusing the container.

## `GTReplayer` [#gt-replayer]

`GTReplayer` mounts `createGTReplayer` into a React-managed container and destroys it on unmount. It recreates the player when `bundle` or `initialLocale` changes.

| Prop | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `bundle` | Recording to play. | `GTReplayerBundle` | No | — |
| `initialLocale` | Locale rendered at mount. | `string` | Yes | `bundle.locales[0]` |
| `switchLocalesAllowed` | Shows locale controls and permits live switching. | `boolean` | Yes | `true` |
| `debug` | Accepts dropped recording JSON files. | `boolean` | Yes | `false` |
| `className` | Class applied to the host container. | `string` | Yes | — |
| `style` | Inline style applied to the host container. | `CSSProperties` | Yes | — |

## `GTReplayerBundle` [#replayer-bundle]

| Field | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `events` | rrweb event stream. | `eventWithTime[]` | No | — |
| `locales` | Available locales with the source first. | `readonly string[]` | Yes | — |
| `overlay` | Locale to rrweb node-id text maps. | `LocaleTextOverlay` | Yes | — |

A raw events-only bundle replays in the recorded source locale. Events emitted by `gt-rrweb` can also carry locale and overlay metadata inside the stream.

## `GTReplayerOptions` [#replayer-options]

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `initialLocale` | Locale rendered at mount; ignored when absent from the bundle. | `string` | Yes | Source locale |
| `switchLocalesAllowed` | Enables the in-player locale switcher. | `boolean` | Yes | `true` |
| `debug` | Enables drag-and-drop bundle replacement for local inspection. | `boolean` | Yes | `false` |

Changing locale replaces text in place without rebuilding playback. Invalid dropped files fail with an in-player notice.

## `GTReplayerHandle` [#replayer-handle]

`GTReplayerHandle` exposes one method, `destroy(): void`, which removes the player and its listeners from the container.