Search
Loading...
Skip to content

Class: EditorAPI

Control the design editor’s behavior and settings.

The EditorAPI provides access to edit modes, history management, editor settings, color management, resource handling, and global scope controls. It serves as the central configuration and control interface for the design editor engine.

Settings API#

The recommended way to work with settings is through the unified API:

  • setSetting<K>(key: K, value: Settings[K]) - Set any setting value
  • getSetting<K>(key: K): Settings[K] - Get any setting value

Legacy methods are available in the deprecated namespace for backward compatibility.

Constructors#

Constructor#


EditorAPI

Role & Scope Management#

Manage user roles and global scope permissions.

setRole()#


Set the user role and apply role-dependent defaults.

Automatically configures scopes and settings based on the specified role.

Parameters#

ParameterTypeDescription
roleRoleStringThe role to assign to the user.

Returns#

void

Signature#

setRole(role: RoleString): void

getRole()#


Get the current user role.

Returns#

RoleString

The current role of the user.

Signature#

getRole(): RoleString

findAllScopes()#


Get all available global scope names.

Returns#

Scope[]

The names of all available global scopes.

Signature#

findAllScopes(): Scope[]

setGlobalScope()#


Set a global scope permission level.

Parameters#

ParameterTypeDescription
keyScopeThe scope to configure.
value"Allow""Deny"

Returns#

void

Signature#

setGlobalScope(key: Scope, value: "Allow" | "Deny" | "Defer"): void

getGlobalScope()#


Get a global scope’s permission level.

Parameters#

ParameterTypeDescription
keyScopeThe scope to query.

Returns#

"Allow" | "Deny" | "Defer"

Allow, Deny, or Defer indicating the scope’s permission level.

Signature#

getGlobalScope(key: Scope): "Allow" | "Deny" | "Defer"

Event Subscriptions#

Subscribe to editor state changes, history updates, and role changes.

onStateChanged()#


Subscribe to editor state changes.

Parameters#

ParameterTypeDescription
callback() => voidFunction called when the editor state changes.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void


onHistoryUpdated()#


Subscribe to undo/redo history changes.

const unsubscribe = engine.editor.onHistoryUpdated(() => {
const canUndo = engine.editor.canUndo();
const canRedo = engine.editor.canRedo();
console.log("History updated", {canUndo, canRedo});
})

Parameters#

ParameterTypeDescription
callback() => voidFunction called when the undo/redo history changes.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void


onSettingsChanged()#


Subscribe to editor settings changes.

Parameters#

ParameterTypeDescription
callback() => voidFunction called when editor settings change.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void


onRoleChanged()#


Subscribe to editor role changes.

Allows reacting to role changes and updating engine settings accordingly. The callback is triggered immediately after role changes and default settings are applied.

Parameters#

ParameterTypeDescription
callback(role) => voidFunction called when the user role changes.

Returns#

A method to unsubscribe from the event.

(): void;
Returns#

void

Edit Mode Management#

Control the editor’s current editing mode and interaction state.

setEditMode()#


Set the editor’s current edit mode.

Edit modes represent different tools or interaction states within the editor. Common ones, are “Crop” while the crop tool is shown or “Text” when inline-editing text.

engine.editor.setEditMode('Crop');
// With a base mode
engine.editor.setEditMode('CustomMode', 'Crop');

Parameters#

ParameterTypeDescription
modeEditMode”Transform”, “Crop”, “Text”, “Playback”, “Trim” or a custom value.
baseMode?stringOptional base mode from which the custom mode will inherit the settings.

Returns#

void

Signature#

setEditMode(mode: EditMode, baseMode?: string): void

getEditMode()#


Get the editor’s current edit mode.

Edit modes represent different tools or interaction states within the editor. Common ones, are “Crop” while the crop tool is shown or “Text” when inline-editing text.

Returns#

EditMode

“Transform”, “Crop”, “Text”, “Playback”, “Trim” or a custom value.

Signature#

getEditMode(): EditMode

getCursorType()#


Get the cursor type that should be displayed.

Returns#

"Text" | "Arrow" | "Move" | "MoveNotPermitted" | "Resize" | "Rotate"

The cursor type.

Signature#

getCursorType(): "Text" | "Arrow" | "Move" | "MoveNotPermitted" | "Resize" | "Rotate"

getCursorRotation()#


Get the cursor rotation angle.

Returns#

number

The angle in radians.

Signature#

getCursorRotation(): number

getTextCursorPositionInScreenSpaceX()#


Get the text cursor’s x position in screen space.

Returns#

number

The text cursor’s x position in screen space.

Signature#

getTextCursorPositionInScreenSpaceX(): number

getTextCursorPositionInScreenSpaceY()#


Get the text cursor’s y position in screen space.

Returns#

number

The text cursor’s y position in screen space.

Signature#

getTextCursorPositionInScreenSpaceY(): number

History Management#

Create, manage, and operate on undo/redo history stacks.

createHistory()#


Create a new undo/redo history stack.

Multiple histories can exist, but only one can be active at a time.

const newHistory = engine.editor.createHistory();

Returns#

number

The handle of the created history.

Signature#

createHistory(): number

destroyHistory()#


Destroy a history stack and free its resources.

engine.editor.destroyHistory(oldHistory);

Parameters#

ParameterTypeDescription
historynumberThe history handle to destroy.

Returns#

void

Throws#

Error if the handle doesn’t refer to a valid history.

Signature#

destroyHistory(history: number): void

setActiveHistory()#


Set a history as the active undo/redo stack.

All other histories lose their active state. Undo/redo operations only apply to the active history.

engine.editor.setActiveHistory(newHistory);

Parameters#

ParameterTypeDescription
historynumberThe history handle to make active.

Returns#

void

Throws#

Error if the handle doesn’t refer to a valid history.

Signature#

setActiveHistory(history: number): void

getActiveHistory()#


Get the currently active history handle.

Creates a new history if none exists.

const oldHistory = engine.editor.getActiveHistory();

Returns#

number

The handle of the active history.

Signature#

getActiveHistory(): number

addUndoStep()#


Add a new history state to the undo stack.

Only adds a state if undoable changes were made since the last undo step.

engine.editor.addUndoStep();

Returns#

void

Signature#

addUndoStep(): void

undo()#


Undo one step in the active history if an undo step is available.

engine.editor.undo();

Returns#

void

Signature#

undo(): void

redo()#


Redo one step in the active history if a redo step is available.

engine.editor.redo();

Returns#

void

Signature#

redo(): void

canUndo()#


Check if an undo step is available.

if (engine.editor.canUndo()) {
engine.editor.undo();
}

Returns#

boolean

True if an undo step is available.

Signature#

canUndo(): boolean

canRedo()#


Check if a redo step is available.

if (engine.editor.canRedo()) {
engine.editor.redo();
}

Returns#

boolean

True if a redo step is available.

Signature#

canRedo(): boolean

Color Management#

Handle spot colors, color conversion, and color space operations.

findAllSpotColors()#


Get all spot color names currently defined.

Returns#

string[]

The names of all defined spot colors.

Signature#

findAllSpotColors(): string[]

getSpotColorRGBA()#


Queries the RGB representation set for a spot color.

If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta). The alpha value is always 1.0.

Parameters#

ParameterTypeDescription
namestringThe name of a spot color.

Returns#

RGBA

A result holding a float array of the four color components.

Signature#

getSpotColorRGBA(name: string): RGBA

getSpotColorCMYK()#


Queries the CMYK representation set for a spot color.

If the value of the queried spot color has not been set yet, returns the default CMYK representation (of magenta).

Parameters#

ParameterTypeDescription
namestringThe name of a spot color.

Returns#

CMYK

A result holding a float array of the four color components.

Signature#

getSpotColorCMYK(name: string): CMYK

setSpotColorRGB()#


Sets the RGB representation of a spot color.

Use this function to both create a new spot color or update an existing spot color.

Parameters#

ParameterTypeDescription
namestringThe name of a spot color.
rnumberThe red color component in the range of 0 to 1.
gnumberThe green color component in the range of 0 to 1.
bnumberThe blue color component in the range of 0 to 1.

Returns#

void

Signature#

setSpotColorRGB(name: string, r: number, g: number, b: number): void

setSpotColorCMYK()#


Sets the CMYK representation of a spot color.

Use this function to both create a new spot color or update an existing spot color.

Parameters#

ParameterTypeDescription
namestringThe name of a spot color.
cnumberThe cyan color component in the range of 0 to 1.
mnumberThe magenta color component in the range of 0 to 1.
ynumberThe yellow color component in the range of 0 to 1.
knumberThe key color component in the range of 0 to 1.

Returns#

void

Signature#

setSpotColorCMYK(name: string, c: number, m: number, y: number, k: number): void

removeSpotColor()#


Removes a spot color from the list of set spot colors.

Parameters#

ParameterTypeDescription
namestringThe name of a spot color.

Returns#

void

An empty result on success, an error otherwise.

Signature#

removeSpotColor(name: string): void

setSpotColorForCutoutType()#


Set the spot color assign to a cutout type.

All cutout blocks of the given type will be immediately assigned that spot color.

Parameters#

ParameterTypeDescription
typeCutoutTypeThe cutout type.
colorstringThe spot color name to assign.

Returns#

void

Signature#

setSpotColorForCutoutType(type: CutoutType, color: string): void

getSpotColorForCutoutType()#


Get the name of the spot color assigned to a cutout type.

Parameters#

ParameterTypeDescription
typeCutoutTypeThe cutout type.

Returns#

string

The color spot name.

Signature#

getSpotColorForCutoutType(type: CutoutType): string

convertColorToColorSpace()#


Converts a color to the given color space.

Parameters#
ParameterTypeDescription
colorColorThe color to convert.
colorSpace"sRGB"The color space to convert to.
Returns#
RGBAColor

The converted color.

Call Signature#

convertColorToColorSpace(color, colorSpace): CMYKColor;
Parameters#
ParameterType
colorColor
colorSpace"CMYK"
Returns#
CMYKColor

Call Signature#

convertColorToColorSpace(color, colorSpace): never;
Parameters#
ParameterType
colorColor
colorSpaceColorSpace
Returns#

never

Signatures#

convertColorToColorSpace(color: Color, colorSpace: "sRGB"): RGBAColor
convertColorToColorSpace(color: Color, colorSpace: "CMYK"): CMYKColor
convertColorToColorSpace(color: Color, colorSpace: ColorSpace): never

Resource Management#

Manage buffers, URIs, and resource data handling.

createBuffer()#


Create a resizable buffer for arbitrary data.

const buffer = engine.editor.createBuffer();
// Reference the buffer resource from the audio block
engine.block.setString(audioBlock, 'audio/fileURI', buffer);

Returns#

string

A URI to identify the created buffer.

Signature#

createBuffer(): string

destroyBuffer()#


Destroy a buffer and free its resources.

engine.editor.destroyBuffer(buffer);

Parameters#

ParameterTypeDescription
uristringThe URI of the buffer to destroy.

Returns#

void

Signature#

destroyBuffer(uri: string): void

setBufferData()#


Set the data of a buffer at a given offset.

// Generate 10 seconds of stereo 48 kHz audio data
const samples = new Float32Array(10 * 2 * 48000);
for (let i = 0; i < samples.length; i += 2) {
samples[i] = samples[i + 1] = Math.sin((440 * i * Math.PI) / 48000);
}
// Assign the audio data to the buffer
engine.editor.setBufferData(buffer, 0, new Uint8Array(samples.buffer));

Parameters#

ParameterTypeDescription
uristringThe URI of the buffer to update.
offsetnumberThe offset in bytes at which to start writing.
dataUint8ArrayThe data to write.

Returns#

void

Signature#

setBufferData(uri: string, offset: number, data: Uint8Array): void

getBufferData()#


Get the data of a buffer at a given offset.

engine.editor.findAllTransientResources().forEach((resource) => {
const bufferURI = resource.url;
const length = engine.editor.getBufferLength(buffer);
const data = engine.editor.getBufferData(buffer, 0, length);
const blob = new Blob([data]);
})

Parameters#

ParameterTypeDescription
uristringThe URI of the buffer to query.
offsetnumberThe offset in bytes at which to start reading.
lengthnumberThe number of bytes to read.

Returns#

Uint8Array

The data at the given offset.

Signature#

getBufferData(uri: string, offset: number, length: number): Uint8Array

setBufferLength()#


Set the length of a buffer.

// Reduce the buffer to half its length
const currentLength = engine.editor.getBufferLength(buffer);
engine.editor.setBufferLength(buffer, currentLength / 2);

Parameters#

ParameterTypeDescription
uristringThe URI of the buffer to update.
lengthnumberThe new length of the buffer in bytes.

Returns#

void

Signature#

setBufferLength(uri: string, length: number): void

getBufferLength()#


Get the length of a buffer.

const length = engine.editor.getBufferLength(buffer);

Parameters#

ParameterTypeDescription
uristringThe URI of the buffer to query.

Returns#

number

The length of the buffer in bytes.

Signature#

getBufferLength(uri: string): number

getMimeType()#


Get the MIME type of a resource.

Downloads the resource if not already cached.

Parameters#

ParameterTypeDescription
uristringThe URI of the resource.

Returns#

Promise<string>

Promise resolving to the resource’s MIME type.

Throws#

Error if the resource cannot be downloaded or MIME type determined.

Signature#

getMimeType(uri: string): Promise<string>

findAllTransientResources()#


Get all transient resources that would be lost during export.

Useful for identifying resources that need relocation (e.g., to a CDN) before export, as these resources are not included in the exported scene.

Returns#

TransientResource[]

The URLs and sizes of transient resources.

Signature#

findAllTransientResources(): TransientResource[]

getResourceData()#


Provides the data of a resource at the given URL.

Parameters#

ParameterTypeDescription
uristringThe URL of the resource.
chunkSizenumberThe size of the chunks in which the resource data is provided.
onData(result) => booleanThe callback function that is called with the resource data or an error if an error occurred. The callback will be called as long as there is data left to provide and the callback returns true.

Returns#

void

Signature#

getResourceData(uri: string, chunkSize: number, onData: (result: Uint8Array) => boolean): void

relocateResource()#


Changes the URL associated with a resource.

This function can be used change the URL of a resource that has been relocated (e.g., to a CDN).

Parameters#

ParameterTypeDescription
currentUrlstringThe current URL of the resource.
relocatedUrlstringThe new URL of the resource.

Returns#

void

Signature#

relocateResource(currentUrl: string, relocatedUrl: string): void

Editor Settings#

Configure editor behavior through typed settings for different data types.

setSetting()#


Set a setting value using the unified API. The type of the value is automatically inferred from the key.

Type Parameters#

Type Parameter
K extends keyof Settings

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<K>The setting key from Settings
valueSettingValueType<K>The value to set (type-safe based on key)

Returns#

void

Throws#

Error if the keypath is invalid or value type doesn’t match

Example#

// Boolean setting
engine.editor.setSetting('doubleClickToCropEnabled', false);
// Color setting
engine.editor.setSetting('highlightColor', { r: 1, g: 0, b: 1, a: 1 });
// Enum setting
engine.editor.setSetting('doubleClickSelectionMode', 'Direct');

Signature#

setSetting(keypath: OptionalPrefix<K>, value: SettingValueType<K>): void

getSetting()#


Get a setting value using the unified API. The return type is automatically inferred from the key.

Type Parameters#

Type Parameter
K extends keyof Settings

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<K>The setting key from Settings

Returns#

SettingValueType<K>

The value of the setting (type-safe based on key)

Throws#

Error if the keypath is invalid

Example#

// Boolean setting
const cropEnabled = engine.editor.getSetting('doubleClickToCropEnabled');
// Color setting
const highlight = engine.editor.getSetting('highlightColor');
// Enum setting
const selectionMode = engine.editor.getSetting('doubleClickSelectionMode');

Signature#

getSetting(keypath: OptionalPrefix<K>): SettingValueType<K>

setSettingBool()#


Set a boolean setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsBool>The settings keypath, e.g. doubleClickToCropEnabled.
valuebooleanThe boolean value to set.

Returns#

void

Deprecated#

Use setSetting() instead.

Throws#

Error if the keypath is invalid.


getSettingBool()#


Get a boolean setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsBool>The settings keypath, e.g. doubleClickToCropEnabled.

Returns#

boolean

The boolean value of the setting.

Deprecated#

Use getSetting() instead.

Throws#

Error if the keypath is invalid.


setSettingInt()#


Set an integer setting value.

Parameters#

ParameterTypeDescription
keypath"maxImageSize"The settings keypath.
valuenumberThe integer value to set.

Returns#

void

Deprecated#

Use setSetting() instead.

Throws#

Error if the keypath is invalid.


getSettingInt()#


Get an integer setting value.

Parameters#

ParameterTypeDescription
keypath"maxImageSize"The settings keypath.

Returns#

number

The integer value of the setting.

Deprecated#

Use getSetting() instead.

Throws#

Error if the keypath is invalid.


setSettingFloat()#


Set a float setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsFloat>The settings keypath, e.g. positionSnappingThreshold.
valuenumberThe float value to set.

Returns#

void

Deprecated#

Use setSetting() instead.

Throws#

Error if the keypath is invalid.


getSettingFloat()#


Get a float setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsFloat>The settings keypath, e.g. positionSnappingThreshold.

Returns#

number

The float value of the setting.

Deprecated#

Use getSetting() instead.

Throws#

Error if the keypath is invalid.


setSettingString()#


Set a string setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsString>The settings keypath, e.g. license.
valuestringThe string value to set.

Returns#

void

Deprecated#

Use setSetting() instead.

Throws#

Error if the keypath is invalid.


getSettingString()#


Get a string setting value.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsString>The settings keypath, e.g. license.

Returns#

string

The string value of the setting.

Deprecated#

Use getSetting() instead.

Throws#

Error if the keypath is invalid.


setSettingColor()#


Set a color setting.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsColor>The settings keypath, e.g. highlightColor.
valueColorThe The value to set.

Returns#

void

Deprecated#

Use setSetting() instead.


getSettingColor()#


Get a color setting.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsColor>The settings keypath, e.g. highlightColor.

Returns#

Color

Deprecated#

Use getSetting() instead.

Throws#

An error, if the keypath is invalid.


setSettingEnum()#


Set an enum setting.

Type Parameters#

Type Parameter
T extends

Parameters#

ParameterTypeDescription
keypathTThe settings keypath, e.g. doubleClickSelectionMode.
valueSettingsEnum[T]The enum value as string.

Returns#

void

Deprecated#

Use setSetting() instead.


getSettingEnum()#


Get an enum setting.

Type Parameters#

Type Parameter
T extends

Parameters#

ParameterTypeDescription
keypathTThe settings keypath, e.g. doubleClickSelectionMode.

Returns#

SettingsEnum[T]

The value as string.

Deprecated#

Use getSetting() instead.


getSettingEnumOptions()#


Get the possible enum options for a given enum setting.

Type Parameters#

Type Parameter
T extends

Parameters#

ParameterTypeDescription
keypathTThe settings keypath, e.g. doubleClickSelectionMode.

Returns#

string[]

The possible enum options as strings.

Signature#

getSettingEnumOptions(keypath: T): string[]

findAllSettings()#


Returns a list of all the settings available.

Returns#

keyof Settings[]

A list of settings keypaths.

Signature#

findAllSettings(): keyof Settings[]

getSettingType()#


Returns the type of a setting.

Parameters#

ParameterTypeDescription
keypathstringThe settings keypath, e.g. doubleClickSelectionMode.

Returns#

SettingType

The setting type.

Signature#

getSettingType(keypath: string): SettingType

setURIResolver()#


Sets a custom URI resolver.

This function can be called more than once. Subsequent calls will overwrite previous calls. To remove a previously set resolver, pass the value null. The given function must return an absolute path with a scheme and cannot be asynchronous. The input is allowed to be invalid URI, e.g., due to placeholders.

// Replace all .jpg files with the IMG.LY logo
engine.editor.setURIResolver((uri) => {
if (uri.endsWith('.jpg')) {
return 'https://img.ly/static/ubq_samples/imgly_logo.jpg';
}
// Make use of the default URI resolution behavior.
return engine.editor.defaultURIResolver(uri);
});

Parameters#

ParameterTypeDescription
resolver(URI, defaultURIResolver) => stringCustom resolution function. The resolution function should not reference variables outside of its scope. It receives the default URI resolver as its second argument

Returns#

void

Signature#

setURIResolver(resolver: (URI: string, defaultURIResolver: (URI: string) => string) => string): void

defaultURIResolver()#


This is the default implementation for the URI resolver.

It resolves the given path relative to the basePath setting.

engine.editor.defaultURIResolver(uri);

Parameters#

ParameterTypeDescription
relativePathstringThe relative path that should be resolved.

Returns#

string

The resolved absolute URI.

Signature#

defaultURIResolver(relativePath: string): string

getAbsoluteURI()#


Resolves the given path.

If a custom resolver has been set with setURIResolver, it invokes it with the given path. Else, it resolves it as relative to the basePath setting. This performs NO validation of whether a file exists at the specified location.

Parameters#

ParameterTypeDescription
relativePathstringA relative path string

Returns#

string

The resolved absolute uri or an error if an invalid path was given.

Signature#

getAbsoluteURI(relativePath: string): string

System Information#

Access memory usage, export limits, and system capabilities.

getAvailableMemory()#


Get the currently available memory.

Returns#

number

The available memory in bytes.

Signature#

getAvailableMemory(): number

getUsedMemory()#


Get the engine’s current memory usage.

Returns#

number

The current memory usage in bytes.

Signature#

getUsedMemory(): number

getMaxExportSize()#


Get the maximum export size limit for the current device.

Exports are only possible when both width and height are below this limit. Note that exports may still fail due to other constraints like memory.

Returns#

number

The upper export size limit in pixels, or maximum 32-bit integer if unlimited.

Signature#

getMaxExportSize(): number

Experimental#

unstable_isInteractionHappening()#

Check if a user interaction is currently happening.

Detects active interactions like resize edits with drag handles or touch gestures.

Returns#

boolean

True if an interaction is happening. This API is experimental and may change or be removed in future versions.

Other#

setSettingColorRGBA()#


Set a color setting.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsColor>The settings keypath, e.g. highlightColor.
rnumberThe red color component in the range of 0 to 1.
gnumberThe green color component in the range of 0 to 1.
bnumberThe blue color component in the range of 0 to 1.
a?numberThe alpha color component in the range of 0 to 1.

Returns#

void

Deprecated#

Use setSettingColor() instead.


getSettingColorRGBA()#


Get a color setting.

Parameters#

ParameterTypeDescription
keypathOptionalPrefix<SettingsColor>The settings keypath, e.g. highlightColor.

Returns#

RGBA

A tuple of channels red, green, blue and alpha in the range of 0 to 1.

Deprecated#

Use getSettingColor() instead.


isHighlightingEnabled()#


Checks wether the block has selection and hover highlighting enabled or disabled.

const highlightingIsEnabled = engine.editor.isHighlightingEnabled(block);

Parameters#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

True if highlighting is enabled, false otherwise.

Signature#

isHighlightingEnabled(id: number): boolean

setHighlightingEnabled()#


Enable or disable selection and hover highlighting for a block.

engine.editor.setHighlightingEnabled(block, true);

Parameters#

ParameterTypeDescription
idnumberThe block to update.
enabledbooleanWhether or not the block should show highlighting when selected or hovered.

Returns#

void

Signature#

setHighlightingEnabled(id: number, enabled: boolean): void