Files

Justin Halsall aab4c553cb docs: revamp installation docs for esm and umd (#1788 )

* docs: revamp installation docs for esm and umd

Document recommended install paths across the main guides and package
READMEs for rrweb, @rrweb/all, @rrweb/record, @rrweb/replay, and
rrweb-player.

Clarify three usage modes: bundler/npm, browser no-build with
import maps and +esm, and legacy UMD fallback.

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Apply formatting changes

* Apply suggestion from @eoghanmurray

Co-authored-by: Eoghan Murray <eoghan@getthere.ie>

* Apply formatting changes

* docs(all): streamline README usage section

Move the guide link next to the import example and remove the
duplicated Usage section to keep docs concise and easier to scan.

* docs(readme): update gzip size badges in zh-cn readme

* docs(plugins): update readme imports to scoped esm packages

Replace `rrweb` default imports and `rrweb.Replayer` usage with
`@rrweb/record` `record` and `@rrweb/replay` `Replayer` in plugin
usage examples.

Also update canvas WebRTC plugin imports to scoped `@rrweb/*`
package names to keep docs aligned with current package structure.

* docs: update docs to prefer scoped esm packages

replace `rrweb` default import examples with `@rrweb/record` and
`@rrweb/replay` across recipes and guides in en/zh-CN.

clarify package selection for new integrations, add `@rrweb/all`
convenience guidance, and refresh CDN/style import snippets for ESM and legacy UMD compatibility.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Eoghan Murray <eoghan@getthere.ie>

2026-04-01 12:00:00 +08:00

15 KiB

Raw Blame History

Looking for a Vue.js version? Go here --> @preflight-hq/rrweb-player-vue

rrweb-player

Since rrweb's replayer only provides a basic UI, you can choose rrweb-replayer which is based on rrweb's public APIs but has a feature-rich replayer UI.

How is this different from `rrweb.Replayer`?

rrweb-player uses rrweb's Replayer under the hood, but as Replayer doesn't include any UI for controls, rrweb-player adds those.

Installation

1) Bundler / npm (Recommended)

npm install rrweb-player

import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';

2) Browser Without Bundler (ESM + import maps)

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script type="importmap">
  {
    "imports": {
      "rrweb-player": "https://cdn.jsdelivr.net/npm/rrweb-player@latest/+esm"
    }
  }
</script>
<script type="module">
  import rrwebPlayer from 'rrweb-player';
</script>

3) Legacy Direct `<script>` Include (UMD fallback)

Use this only for compatibility with non-module environments.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@latest/umd/rrweb-player.min.js"></script>

Usage

new rrwebPlayer({
  target: document.body, // customizable root element
  props: {
    events,
  },
});

Options

key	default	description
events	[]	the events for replaying
width	1024	the width of the replayer
height	576	the height of the replayer
maxScale	1	the maximum scale of the replayer (1 = 100%), set to 0 for unlimited
autoPlay	true	whether to autoplay
speed	1	The default speed to play at
speedOption	[1, 2, 4, 8]	speed options in UI
showController	true	whether to show the controller UI
tags	{}	customize the custom events style with a key-value map
inactiveColor	#D4D4D4	Customize the color of inactive periods indicator in the progress bar with a valid CSS color string.
...	-	all the rrweb Replayer options will be bypassed

methods on the rrwebPlayer component

addEventListener(event: string, handler: (params: any) => unknown): void;

addEvent(event: eventWithTime): void;

getMetaData() => {
    startTime: number;
    endTime: number;
    totalTime: number;
}

getReplayer() => Replayer;

getMirror() => Mirror;

Toggles between play/pause

toggle();

Sets speed of player

setSpeed(speed: number)

Turns on/off skip inactive

toggleSkipInactive();

Triggers resize, do this whenever you change width/height

triggerResize();

Plays replay

play();

Pauses replay

pause();

Go to a point in time and pause or play from then

goto(timeOffset: number, play?: boolean)

Plays from a time to a time and (optionally) loop

playRange(
    timeOffset: number,
    endTimeOffset: number,
    startLooping: boolean = false,
    afterHook: undefined | (() => void) = undefined,
  )