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.
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 |
---|---|---|
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.
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#
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
.
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 |
---|---|---|
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#
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#
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.
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 |
---|---|---|
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#
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#
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