Class: UserInterfaceAPI

Control the user interface and behavior of the Creative Editor SDK.

The UserInterfaceAPI provides comprehensive methods for managing panels, notifications, dialogs, component registration, UI ordering, asset libraries, and custom interface elements within the editor.

Experimental Features#

Experimental APIs that may change or be removed in future versions.

unstable_registerCustomPanel()#

Registers a custom panel that hooks into a DOM element for custom UI rendering.

The onMount function is called when the panel opens, and its return value (if a function) is called when the panel closes for cleanup.

Parameters#

Parameter	Type	Description
`panelId`	`string`	The unique ID for the custom panel.
`onMount`	`CustomPanelMountFunction`	Function called when the panel is mounted, should return a cleanup function. This API may change or be removed in future versions.

Returns#

void

unstable_getView()#

Gets the current view style of the editor interface.

Returns#

ViewStyle

The current view style (‘default’ or ‘advanced’). This API may change or be removed in future versions.

Asset Library#

Methods for managing asset library entries and configurations.

addAssetLibraryEntry()#

Adds a new asset library entry for display in asset libraries.

If an entry with the same ID already exists, it will be replaced. The method validates sorting configurations and warns about duplicates.

Parameters#

Parameter	Type	Description
`AssetLibraryEntry`	`AssetLibraryEntry`	The asset library entry configuration to add.

Returns#

void

Signature#

addAssetLibraryEntry(AssetLibraryEntry: AssetLibraryEntry): void

updateAssetLibraryEntry()#

Updates an existing asset library entry with new properties.

The provided properties will be merged with the existing entry.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the asset library entry to update.
`assetLibraryEntry`	`Partial`<`Omit`<`AssetLibraryEntry`, `"id"`>>	Partial entry properties to merge with the existing entry.

Returns#

void

Signature#

updateAssetLibraryEntry(id: string, assetLibraryEntry: Partial<Omit<AssetLibraryEntry, "id">>): void

removeAssetLibraryEntry()#

Removes an asset library entry from the available entries.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the asset library entry to remove.

Returns#

void

Signature#

removeAssetLibraryEntry(id: string): void

getAssetLibraryEntry()#

Gets a specific asset library entry by its ID.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the asset library entry to retrieve.

Returns#

| undefined | AssetLibraryEntry

The asset library entry configuration, or undefined if not found.

Signature#

getAssetLibraryEntry(id: string): undefined | AssetLibraryEntry

findAllAssetLibraryEntries()#

Gets all currently registered asset library entry IDs.

Returns#

string[]

Array of asset library entry IDs.

Signature#

findAllAssetLibraryEntries(): string[]

setBackgroundTrackAssetLibraryEntries()#

Sets the asset library entries to use for the background track in video scenes.

This setting only affects video scenes and has no impact on other scene types.

Parameters#

Parameter	Type	Description
`backgroundTrackAssetLibraryEntries`	`string`[]	Array of asset library entry IDs for the background track.

Returns#

void

Signature#

setBackgroundTrackAssetLibraryEntries(backgroundTrackAssetLibraryEntries: string[]): void

getBackgroundTrackAssetLibraryEntries()#

Gets the asset library entries configured for the background track in video scenes.

This setting only affects video scenes and has no impact on other scene types.

Returns#

string[]

Array of asset library entry IDs configured for the background track.

Signature#

getBackgroundTrackAssetLibraryEntries(): string[]

setReplaceAssetLibraryEntries()#

Sets a function that determines which asset library entries to use for replacement operations.

The function receives context information (like selected blocks or default entry IDs) and returns the appropriate asset library entry IDs for replacement.

Parameters#

Parameter	Type	Description
`replaceAssetLibraryEntries`	(`context`) => `string`[]	Function that receives context and returns an array of asset library entry IDs for replacement.

Returns#

void

Signature#

setReplaceAssetLibraryEntries(replaceAssetLibraryEntries: (context: ReplaceAssetLibraryEntriesContext) => string[]): void

Component Registration#

Methods for registering custom components and panels in the editor.

registerPanel()#

Registers a panel with builder-based rendering system.

The builder render function will be called with a builder and the engine as arguments. The builder object is used to defined what base components should be rendered (such as a button). The engine can be used to get any state from the engine. The render function will be re-called if anything in the engine changes regarding the made engine calls.

Type Parameters#

Type Parameter	Default type
`P` extends `ComponentPayload`	`ComponentPayload`

Parameters#

Parameter	Type	Description
`panelId`	`string`	The panel ID for use with panel management APIs.
`renderPanel`	`BuilderRenderFunction`<`P`>	Function that renders the panel content using the builder system.

Returns#

void

Signature#

registerPanel(panelId: string, renderPanel: BuilderRenderFunction<P>): void

unstable_registerPanel()#

Registers a panel with builder-based rendering system.

Type Parameters#

Type Parameter	Default type
`P` extends `ComponentPayload`	`ComponentPayload`

Parameters#

Parameter	Type	Description
`panelId`	`string`	The panel ID for use with panel management APIs.
`renderComponent`	`BuilderRenderFunction`<`P`>	Function that renders the panel content using the builder system.

Returns#

void

Deprecated#

Use registerPanel instead.

registerComponent()#

Registers a component that can be rendered at different UI locations.

Type Parameters#

Type Parameter	Default type
`P` extends `ComponentPayload`	`ComponentPayload`

Parameters#

Parameter	Type	Description
`ids`	`string`	`string`[]
`renderComponent`	`BuilderRenderFunction`<`P`>	Function that renders the component using the builder system.

Returns#

void

Signature#

registerComponent(ids: string | string[], renderComponent: BuilderRenderFunction<P>): void

Dialogs#

Methods for showing, updating, and closing modal dialogs.

showDialog()#

Displays a modal dialog with custom content and actions.

Dialogs can have different types (info, success, warning, error, loading) and support custom actions like OK, Cancel, or custom buttons.

Parameters#

Parameter	Type	Description
`dialog`	`string`	`Dialog`

Returns#

string

The dialog ID for programmatic updates or closure.

Signature#

showDialog(dialog: string | Dialog): string

updateDialog()#

Updates an existing dialog with new content or properties.

The dialog properties will be merged with the existing dialog configuration.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the dialog to update.
`dialog`		`Partial`<`Dialog`>

Returns#

void

Signature#

updateDialog(id: string, dialog: Partial<Dialog> | (dialog: Dialog) => Partial<Dialog>): void

closeDialog()#

Closes a dialog programmatically.

If the dialog has an onClose callback, it will be executed before removal. Closing an already closed dialog has no effect.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the dialog to close.

Returns#

void

Signature#

closeDialog(id: string): void

Notifications#

Methods for displaying and managing user notifications and messages.

showNotification()#

Displays a non-blocking notification message to the user.

Notifications appear temporarily and can be dismissed by the user. They support different types (info, success, warning, error) and durations.

Parameters#

Parameter	Type	Description
`notification`		`string`

Returns#

string

The notification ID for programmatic updates or dismissal.

Signature#

showNotification(notification: string | Notification): string

dismissNotification()#

Dismisses a notification programmatically.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the notification to dismiss.

Returns#

void

Signature#

dismissNotification(id: string): void

updateNotification()#

Updates an existing notification with new content or properties.

The notification object will be merged with the existing notification. If the duration is updated, the timeout will be reset. Updates to dismissed notifications are ignored.

Parameters#

Parameter	Type	Description
`id`	`string`	The ID of the notification to update.
`notification`	`Partial`<`Notification`>	Partial notification properties to merge.

Returns#

void

Signature#

updateNotification(id: string, notification: Partial<Notification>): void

Other#

experimental#

PLEASE NOTE: This contains experimental APIs.

Use them with caution since they might change without warning and might be replaced with a completely different concept or maybe not at all.

applyForceCrop()#

programmatically applies a crop preset to a design block.

This is useful in scenarios where you want to enforce a particular format (e.g., fixed aspect ratio) and define how the editor should respond after the preset is applied.

Parameters#

Parameter	Type	Description
`id`	`number`	The ID of the design block to apply the crop preset to.
`options`	{ `sourceId`: `string`; `presetId`: `string`; `mode`: `"silent"`	`"always"`
`options.sourceId`	`string`	-
`options.presetId`	`string`	-
`options.mode`	`"silent"`	`"always"`

Returns#

Promise<void>

Signature#

applyForceCrop(id: number, options: object): Promise<void>

Panel Management#

Methods for opening, closing, and configuring panels within the editor interface.

openPanel()#

Opens a panel if it exists, is not already open, and is currently registered.

If requirements are not met, this is a no-op.

Available built-in panel IDs:

//ly.img.panel/inspector - Opens the inspector panel for the selected block
//ly.img.panel/assetLibrary.replace - Opens the asset library for replacing the selected block. Beware that the library might show nothing depending on how it was configured.

Type Parameters#

Type Parameter
`T` extends `PanelId`

Parameters#

Parameter	Type	Description
`panelId`	`T`	The ID of the panel to open.
`options?`	`PanelOptions`<`T`>	Optional configuration for panel position and floating state.

Returns#

void

Signature#

openPanel(panelId: T, options?: PanelOptions<T>): void

closePanel()#

Closes a panel if it exists and is currently open.

Otherwise the method does nothing and is a noop.

Available built-in panel IDs:

//ly.img.panel/inspector - Closes the inspector panel
//ly.img.panel/assetLibrary - Closes the asset library
//ly.img.panel/assetLibrary.replace - Closes the replacement asset library

Parameters#

Parameter	Type	Description
`panelId`	`string`	The ID of the panel to close.

Returns#

void

Signature#

closePanel(panelId: string): void

isPanelOpen()#

Checks if a panel is currently open.

Available built-in panel IDs:

//ly.img.panel/inspector - Inspector panel for the selected block
//ly.img.panel/assetLibrary - Asset library panel
//ly.img.panel/assetLibrary.replace - Replacement asset library panel

Type Parameters#

Type Parameter
`T` extends `PanelId`

Parameters#

Parameter	Type	Description
`panelId`	`T`	The ID of the panel to check.
`options?`	`PanelOptions`<`T`>	Optional criteria to match against the panel’s current state.

Returns#

boolean

True if the panel is open and matches the specified options, false otherwise.

Signature#

isPanelOpen(panelId: T, options?: PanelOptions<T>): boolean

findAllPanels()#

Gets all panel IDs, optionally filtered by state or position.

Type Parameters#

Type Parameter
`T` extends `PanelId`

Parameters#

Parameter	Type	Description
`options?`	`PanelOptions`<`T`> & `object`	Optional filter criteria for panel state and position.

Returns#

string[]

Array of panel IDs matching the specified criteria.

Example#

cesdk.ui.findAllPanels();
cesdk.ui.findAllPanels({ open: true, position: 'left' });

Signature#

findAllPanels(options?: PanelOptions<T> & object): string[]

setPanelPosition()#

Sets the position of a panel within the editor interface.

Parameters#

Parameter	Type	Description
`panelId`	`string`	The ID of the panel to position.
`panelPosition`		`PanelPosition`

Returns#

void

Signature#

setPanelPosition(panelId: string, panelPosition: PanelPosition | () => PanelPosition): void

getPanelPosition()#

Gets the current position of a panel.

Parameters#

Parameter	Type	Description
`panelId`	`string`	The ID of the panel.

Returns#

PanelPosition

The panel’s position (‘left’ or ‘right’).

Signature#

getPanelPosition(panelId: string): PanelPosition

setPanelFloating()#

Sets whether a panel floats over the canvas.

Parameters#

Parameter	Type	Description
`panelId`	`string`	The ID of the panel to configure.
`floating`	`boolean`	() => `boolean`

Returns#

void

Signature#

setPanelFloating(panelId: string, floating: boolean | () => boolean): void

getPanelFloating()#

Checks if a panel is currently floating over the canvas.

Parameters#

Parameter	Type	Description
`panelId`	`string`	The ID of the panel to check.

Returns#

boolean

True if the panel is floating, false if it’s docked.

Signature#

getPanelFloating(panelId: string): boolean

UI Layout#

Methods for controlling the order and arrangement of UI components.

setDockOrder()#

Sets the rendering order of components in the dock area.

The ids in this order refer to registered default components or custom components registered in registerComponent.

Different orders can be set depending on different contexts. The context consists of the edit mode (e.g. Transform or Text) right now. If no context is given, the default order is set for the Transform edit mode.

Parameters#

Parameter	Type	Description
`dockOrder`	(	`DockOrderComponentId`
`orderContext?`	`OrderContext`	Optional context specifying when this order applies.

Returns#

void

Signature#

setDockOrder(dockOrder: DockOrderComponentId | DockOrderComponent[], orderContext?: OrderContext): void

getDockOrder()#

Gets the current rendering order of dock components.

The id in this order refer to registered default components or custom components registered in registerComponent.

Different orders could have been set depending on different contexts. The context consists of the edit mode (e.g. Transform or Text) right now. If no context is given, the default order (with Transform edit mode) is returned.

Parameters#

Parameter	Type	Description
`orderContext?`	`OrderContext`	Optional context specifying which order to retrieve.

Returns#

DockOrderComponent[]

Array of component configurations defining the dock order.

Signature#

getDockOrder(orderContext?: OrderContext): DockOrderComponent[]

setInspectorBarOrder()#

Sets the rendering order of components in the inspector bar.

The id in this order refer to registered default components or custom components registered in registerComponent.

Parameters#

Parameter	Type	Description
`inspectorBarOrder`	(	`InspectorBarComponentId`
`orderContext?`	`OrderContext`	Optional context specifying when this order applies.

Returns#

void

Signature#

setInspectorBarOrder(inspectorBarOrder: InspectorBarComponentId | OrderComponent<InspectorBarComponentId>[], orderContext?: OrderContext): void

getInspectorBarOrder()#

Gets the current rendering order of inspector bar components.

Component IDs refer to built-in components or those registered via registerComponent. Returns the order for the specified context, or defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`orderContext?`	`OrderContext`	Optional context specifying which order to retrieve.

Returns#

OrderComponent<ComponentId>[]

Array of component configurations defining the inspector bar order.

Signature#

getInspectorBarOrder(orderContext?: OrderContext): OrderComponent<ComponentId>[]

setCanvasMenuOrder()#

Sets the rendering order of components in the canvas menu.

Component IDs refer to built-in components or those registered via registerComponent. Different orders can be set for different contexts (e.g., Transform or Text edit modes). Defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`canvasMenuOrder`	(	`CanvasMenuComponentId`
`orderContext?`	`OrderContext`	Optional context specifying when this order applies.

Returns#

void

Signature#

setCanvasMenuOrder(canvasMenuOrder: CanvasMenuComponentId | OrderComponent<CanvasMenuComponentId>[], orderContext?: OrderContext): void

getCanvasMenuOrder()#

Gets the current rendering order of canvas menu components.

Component IDs refer to built-in components or those registered via registerComponent. Returns the order for the specified context, or defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`orderContext?`	`OrderContext`	Optional context specifying which order to retrieve.

Returns#

OrderComponent<ComponentId>[]

Array of component configurations defining the canvas menu order.

Signature#

getCanvasMenuOrder(orderContext?: OrderContext): OrderComponent<ComponentId>[]

setNavigationBarOrder()#

Sets the rendering order of components in the navigation bar.

Parameters#

Parameter	Type	Description
`navigationBarOrder`	(	`NavigationBarComponentId`
`orderContext?`	`OrderContext`	Optional context specifying when this order applies.

Returns#

void

Signature#

setNavigationBarOrder(navigationBarOrder: NavigationBarComponentId | OrderComponent<NavigationBarComponentId>[], orderContext?: OrderContext): void

getNavigationBarOrder()#

Gets the current rendering order of navigation bar components.

Component IDs refer to built-in components or those registered via registerComponent. Returns the order for the specified context, or defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`orderContext?`	`OrderContext`	Optional context specifying which order to retrieve.

Returns#

OrderComponent<ComponentId>[]

Array of component configurations defining the navigation bar order.

Signature#

getNavigationBarOrder(orderContext?: OrderContext): OrderComponent<ComponentId>[]

setCanvasBarOrder()#

Sets the rendering order of components in the canvas bar.

Component IDs refer to built-in components or those registered via registerComponent. Canvas bars can be positioned at the top or bottom of the canvas. Different orders can be set for different contexts (e.g., Transform or Text edit modes). Defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`canvasBarOrder`	(	`CanvasBarComponentId`
`position`	`"top"`	`"bottom"`
`orderContext?`	`OrderContext`	Optional context specifying when this order applies.

Returns#

void

Signature#

setCanvasBarOrder(canvasBarOrder: CanvasBarComponentId | OrderComponent<CanvasBarComponentId>[], position: "top" | "bottom", orderContext?: OrderContext): void

getCanvasBarOrder()#

Gets the current rendering order of canvas bar components at the specified position.

Component IDs refer to built-in components or those registered via registerComponent. Returns the order for the specified context, or defaults to Transform mode if no context is provided.

Parameters#

Parameter	Type	Description
`position`	`"top"`	`"bottom"`
`orderContext?`	`OrderContext`	Optional context specifying which order to retrieve.

Returns#

OrderComponent<ComponentId>[]

Array of component configurations defining the canvas bar order.

Signature#

getCanvasBarOrder(position: "top" | "bottom", orderContext?: OrderContext): OrderComponent<ComponentId>[]

addIconSet()#

Adds a custom icon set to the editor interface.

The icon set should be an SVG sprite containing symbol elements. Symbol IDs must start with ’@’ to be recognized by the editor.

Security Warning: The SVG sprite is injected into the DOM without sanitization. Only use trusted sources to prevent XSS attacks. Consider using libraries like DOMPurify for untrusted content.

Parameters#

Parameter	Type	Description
`id`	`string`	The unique identifier for the icon set.
`svgSprite`	`string`	The SVG sprite string containing symbol definitions.

Returns#

void

Signature#

addIconSet(id: string, svgSprite: string): void