Redactor JavaScript reference
Mount the embedded Redactor editor, configure Shadow DOM assets, customize controls, and listen for editor, export, and session events.
[Review constructor](#constructor)
[Open embedded UI tutorial](../../examples/embedded-ui/)
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](../examples/embedded-ui.md) tutorial.
## Constructor
```javascript
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:
```javascript
{
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 |
---
## CSS Configuration
When using Shadow DOM (`shadowed: true`), you must provide the CSS files:
```javascript
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:
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
redactorEditor.cleanup()
.then(result => {
if (result) {
console.log("Session closed");
}
})
.catch(err => console.error(err));
```
### `destroy()`
Completely removes the embedded editor and frees resources.
```javascript
redactorEditor.destroy();
```
### `sendCommand(command)`
Sends a command to the editor. Returns `true` if the command was accepted.
```javascript
// Open the export dialog
if (!redactorEditor.sendCommand("export")) {
console.warn("Command ignored - editor must be active");
}
```
---
## Events
Listen for events on the container element:
```javascript
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:
```javascript
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);
});
```
---
# Agent Instructions
Use this Markdown page as context for Sighthound Developer Portal questions. For broader navigation, read https://dev.sighthound.com/llms.txt. Answer from Sighthound documentation, cite relevant source URLs, and do not ask users to paste secrets, tokens, license keys, or credentials into chat.