URL Parameters

Configure the rooomAvatars Editor behavior using URL query parameters and hash fragments.

Use URL query parameters for editor display settings and a hash fragment for the API token.

Overview

Build the editor URL in this order: editor origin, query string, then hash fragment.

https://editor.avatars.rooom.com/?transparent&theme=light#token=API_TOKEN

Query parameters are part of the URL before #. The token belongs in the hash fragment as #token=API_TOKEN, not in the query string.

INFO

Browsers do not send hash fragments to the server in HTTP requests. The editor reads token on load and removes the fragment from the visible URL.

Query parameters

Parameter	Value	Effect
transparent	(flag)	Makes the background transparent.
full	(flag)	Enables full-screen layout mode.
name	0	Hides the avatar name input field. Any other value (or missing) shows it.
doneAnimation	0	Disables the "done" animation. Any other value (or missing) enables it.
lng	de, en, fr, es, it, pt, nl	Overrides the UI language. If missing, the browser language is used (fallback: en).
theme	light / dark	Sets the UI theme. If missing (or an invalid value is provided), the default theme is used.
config	URL-encoded JSON	Initial avatar settings JSON applied on load (see Configuration Schema).
avatarName	string	Initial avatar name pre-filled on load.
close	(flag)	Shows a close button (×) in the editor header and enables closing via the Esc key. When the user closes the editor, a rooom-avatars-closed message is sent to the parent window.
closeOutside	(flag)	Closes the editor when the user clicks the backdrop outside the editor. Closing emits the same rooom-avatars-closed message. Typically combined with close, but works independently.

Hash fragment

Fragment key	Value	Effect
token	API_TOKEN	API bearer token used by the editor when it registers the avatar. Required for saving.

Examples

Use a transparent editor background with the API token in the hash fragment:

<!-- API_TOKEN is the token for your rooomAvatars integration. -->
<iframe
  src="https://editor.avatars.rooom.com/?transparent#token=API_TOKEN"
  title="rooomAvatars Editor"
  allow="camera *; clipboard-read; clipboard-write"
></iframe>

Pass multiple display options before the hash fragment:

<!-- API_TOKEN is the token for your rooomAvatars integration. -->
<iframe
  src="https://editor.avatars.rooom.com/?transparent&full&theme=light&lng=de#token=API_TOKEN"
  title="rooomAvatars Editor"
  allow="camera *; clipboard-read; clipboard-write"
></iframe>

Enable the close button, Esc key, and click-outside-to-close. Listen for the rooom-avatars-closed message to remove or hide the iframe:

<!-- API_TOKEN is the token for your rooomAvatars integration. -->
<iframe
  src="https://editor.avatars.rooom.com/?close&closeOutside#token=API_TOKEN"
  title="rooomAvatars Editor"
  allow="camera *; clipboard-read; clipboard-write"
></iframe>

Encode the config value with encodeURIComponent(JSON.stringify(config)) before adding it to the URL:

const config = { version: '1.0.0' };
const encodedConfig = encodeURIComponent(JSON.stringify(config));
// API_TOKEN is the token for your rooomAvatars integration.
const src = `https://editor.avatars.rooom.com/?config=${encodedConfig}#token=API_TOKEN`;

Replace API_TOKEN with the token for your rooomAvatars integration.