Embedded Editor JavaScript API

Redactor JavaScript reference

Mount the embedded Redactor editor, configure Shadow DOM assets, customize controls, and listen for editor, export, and session events.

Review constructor Open embedded UI tutorial

Mount editor

Create an editor instance with a target element, Redactor server URL, project/session selector, and options.

Configure behavior

Control CSS assets, translations, export buttons, and session actions for embedded workflows.

Listen for events

Observe editor enter/exit, export, and session events to coordinate application-side actions.

This reference documents the JavaScript API for embedding the Redactor editor into your web application. For a step-by-step guide on setting up the embedded editor, see the Embedded Redactor UI tutorial.

Constructor

const redactorEditor = new redactor.default(
    element,        // DOM element where editor renders
    serverUrl,      // Redactor server/proxy URL
    whereTo,        // Project/session selection
    options         // Configuration options
);

element

The DOM element where the Redactor editor will render. The editor expands to fill this element's dimensions.

serverUrl

The base URL of your Redactor server or proxy (e.g., "https://yourdomain.com/proxy/redactor").

whereTo

An object specifying which project and optionally which session to display:

{
    projectId: "my-project-id",  // Required: matches projectId from MEDIA_PREPARE
    sessionId: ""                // Optional: open a specific video directly
}

options

Configuration options for the editor:

Option	Type	Description
shadowed	boolean	Use Shadow DOM for style isolation (recommended: true)
cssHref	object	CSS file URLs (required when shadowed: true)
customize	object	UI customization options
translationOverwritesUrl	string	URL to custom translation file
tenantToken	string	Customer-minted, customer-signed JWT that zones this embedded session to a single tenant (multi-tenant deployments only). See Multi-tenant token.

Multi-tenant token

When the Redactor server runs in multi-tenant zoning mode, each embedded session must be scoped to a single tenant. Your application supplies that scope through the tenantToken option: a JSON Web Token (JWT) that you mint and sign with your own private key. Redactor only ever verifies the token against the public key(s) the operator has configured — it never mints or signs tokens itself.

The token's tenantId claim is stamped onto every session, video, thumbnail, and export the tenant creates, and is enforced on session access, the media endpoints, and the Socket.IO handshake, so a tenant can only ever reach its own data.

const redactorEditor = new redactor.default(
    element,
    serverUrl,
    whereTo,
    {
        shadowed: true,
        cssHref: { /* ... */ },
        // Customer-minted, customer-signed JWT carrying the tenantId claim
        tenantToken: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
);

Server configuration required

tenantToken takes effect only when the Redactor server is started with tenant zoning enabled (REDACTOR_TENANT_PUBLIC_KEYS). See Multi-Tenant Zoning (JWT) for the full server-side setup, including key material, accepted algorithms, and the cross-site cookie and CORS requirements.

---

CSS Configuration

When using Shadow DOM (shadowed: true), you must provide the CSS files:

cssHref: {
    fonts: [
        "/proxy/redactor/public/sighthound-redactor-fonts.css"
    ],
    main: [
        "/proxy/redactor/public/sighthound-redactor.css",
        "/path/to/your-custom-overrides.css"  // Optional
    ]
}

---

Customization Options

Control the visibility and behavior of UI elements:

customize: {
    export: {
        download: "show",  // "show", "hide", or "eventOnly"
        save: "hide"       // "show", "hide", or "eventOnly"
    },
    session: {
        remove: "show",              // "show", "hide", or "eventOnly"
        deleteRedactionData: "show"  // "show" or "hide"
    }
}

Value	Behavior
"show"	Display the button/menu item and perform the default action
"hide"	Hide the button/menu item completely
"eventOnly"	Display the button/menu item but only emit an event (no default action)

---

Methods

renderEditor(callback)

Renders the editor into the container element. Call this after your MEDIA_PREPARE operation completes.

redactorEditor.renderEditor((err) => {
    if (err) {
        console.error("Render failed:", err);
    }
});

active()

Returns true if a video is currently open in the editor, false if showing the project list.

if (redactorEditor.active()) {
    console.log("A video is open");
}

cleanup()

Closes the currently open video session. Returns a Promise. Call this before making API calls that operate on the same session.

redactorEditor.cleanup()
    .then(result => {
        if (result) {
            console.log("Session closed");
        }
    })
    .catch(err => console.error(err));

destroy()

Completely removes the embedded editor and frees resources.

redactorEditor.destroy();

sendCommand(command)

Sends a command to the editor. Returns true if the command was accepted.

// Open the export dialog
if (!redactorEditor.sendCommand("export")) {
    console.warn("Command ignored - editor must be active");
}

---

Events

Listen for events on the container element:

const redactorElement = document.getElementById("redactor-editor");

redactorElement.addEventListener("redactor.editor.enter", (evt) => {
    console.log("Video opened:", evt.detail.sessionId);
});

Editor Events

Event	Description	Detail
redactor.editor.enter	A video was opened	{ sessionId }
redactor.editor.exit	A video was closed	{ sessionId }

Export Events

Event	Description	Detail
redactor.export.cancel	Export dialog was closed/cancelled	{ sessionId }
redactor.export.download	Download button clicked	{ sessionId, renderConfig }
redactor.export.save	Save button clicked	{ sessionId, renderConfig }
redactor.export.submit	Submit/render button clicked	{ sessionId, renderConfig }

Session Events

Event	Description	Detail
redactor.session.remove	Remove menu item clicked	{ sessionId }
redactor.session.delete_redaction_data	Delete redaction data clicked	{ sessionId }

Intercepting Events

Use evt.preventDefault() to intercept an action and handle it yourself:

redactorElement.addEventListener("redactor.export.submit", (evt) => {
    evt.preventDefault();  // Prevent automatic rendering

    // Handle the export via your own backend
    const { sessionId, renderConfig } = evt.detail;
    yourBackend.startRender(sessionId, renderConfig);
});