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.

Constructors#

Constructor#

UserInterfaceAPI

Experimental Features#

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’).

Deprecated#

Use getView() instead. This experimental API will be removed in a future version. This API may change or be removed in future versions.

Example#

// Before (deprecated)
const view = cesdk.ui.unstable_getView();

// After (preferred)
const view = cesdk.ui.getView();

Asset Library#

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`	`AssetEntryId`	The ID of the asset library entry to update.
`assetLibraryEntry`		`Partial`<`Omit`<`AssetLibraryEntry`, `"id"`

Returns#

void

Example#

// Simple static update
cesdk.ui.updateAssetLibraryEntry('ly.img.colors', {
  sourceIds: ['my-custom-colors']
});

// Update other properties using callback with entry
cesdk.ui.updateAssetLibraryEntry('ly.img.pagePresets', (entry) => ({
  title: entry?.title ? `${entry.title} (Custom)` : 'Page Formats',
  icon: { name: 'format-icon' }
}));

// Extend sourceIds with lazy resolution (preserves dynamic behavior)
cesdk.ui.updateAssetLibraryEntry('ly.img.typefaces', {
  sourceIds: ({ currentIds }) => [...currentIds, 'my-custom-fonts']
});

Signature#

updateAssetLibraryEntry(id: AssetEntryId, assetLibraryEntry: Partial<Omit<AssetLibraryEntry, "id" | "sourceIds"> & object> | (entry: AssetLibraryEntry) => Partial<Omit<AssetLibraryEntry, "id" | "sourceIds"> & object>): void

removeAssetLibraryEntry()#

Removes an asset library entry from the available entries.

Parameters#

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

Returns#

void

Signature#

removeAssetLibraryEntry(id: AssetEntryId): void

getAssetLibraryEntry()#

Gets a specific asset library entry by its ID.

Parameters#

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

Returns#

AssetLibraryEntry

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

Signature#

getAssetLibraryEntry(id: AssetEntryId): AssetLibraryEntry

findAllAssetLibraryEntries()#

Gets all currently registered asset library entry IDs.

Returns#

AssetEntryId[]

Array of asset library entry IDs.

Signature#

findAllAssetLibraryEntries(): AssetEntryId[]

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`	`AssetEntryId`[]	Array of asset library entry IDs for the background track.

Returns#

void

Deprecated#

please use the cesdk.actions API to register an action for ‘addClip’ and implement your own logic.

Example#

// Before
cesdk.ui.setBackgroundTrackAssetLibraryEntries(['ly.img.video', 'ly.img.image']);
// After
cesdk.actions.register('addClip', async () => {
  cesdk.ui.openPanel('//ly.img.panel/assetLibrary', {
    payload: {
      entries: ['ly.img.video', 'ly.img.image']
    }
  });
});

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#

AssetEntryId[]

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

Deprecated#

The background track entries are now defined via the cesdk.actions API.

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`) => `AssetEntryId`[]	Function that receives context and returns an array of asset library entry IDs for replacement.

Returns#

void

Signature#

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

Component Registration#

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#

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#

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_2): 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_2>): 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.

getView()#

Gets the current view style of the editor interface.

The view style controls the complexity and feature set shown in the UI. ‘default’ provides a simplified interface, while ‘advanced’ shows more comprehensive editing tools and options.

Returns#

ViewStyle

The current view style (‘default’ or ‘advanced’).

Example#

// Get the current view style
const viewStyle = cesdk.ui.getView(); // 'default' or 'advanced'

// Use for conditional UI logic
const showAdvancedOptions = cesdk.ui.getView() === 'advanced';

// Switch to advanced mode if currently in default
if (cesdk.ui.getView() === 'default') {
  cesdk.ui.setView('advanced');
}

Signature#

getView(): ViewStyle

setView()#

Sets the view style of the editor interface.

This immediately updates the UI to reflect the new view style. The view style controls which UI elements and features are available.

Parameters#

Parameter	Type	Description
`view`	`ViewStyle`	The view style to set (‘default’ or ‘advanced’).

Returns#

void

Example#

// Set view to advanced mode
cesdk.ui.setView('advanced');

// Set view to simplified mode
cesdk.ui.setView('default');

// Toggle between view styles
const currentView = cesdk.ui.getView();
const newView = currentView === 'advanced' ? 'default' : 'advanced';
cesdk.ui.setView(newView);

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#

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 panels that match the given pattern. Supports wildcard matching.

Available built-in panel IDs:

//ly.img.panel/inspector - Inspector panel
//ly.img.panel/assetLibrary - Asset library
//ly.img.panel/assetLibrary.replace - Replacement asset library

Parameters#

Parameter	Type	Description
`panelId`	`string`	The panel ID or pattern to match panels for closing.

Returns#

void

Example#

// Close a specific panel by exact ID
cesdk.ui.closePanel('//ly.img.panel/inspector');

// Close all ly.img panels using wildcard
cesdk.ui.closePanel('//ly.img.*');

// Close all panels with specific prefix
cesdk.ui.closePanel('//ly.img.panel/*');

// Close panels matching complex pattern
cesdk.ui.closePanel('//ly.img.panel/' + '*' + '/stroke/' + '*');

// Close any inspector panels regardless of namespace
cesdk.ui.closePanel('*' + '/inspector');

// Close all asset library panels
cesdk.ui.closePanel('*assetLibrary*');

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

Theme Management#

getTheme()#

Gets the resolved theme that is currently being used. If the theme configuration is ‘system’, returns the OS preference. If the theme configuration is a function, it is evaluated lazily and the result is returned.

Returns#

Theme

The resolved theme (‘light’ or ‘dark’).

Example#

// Get the actual theme being used
const theme = cesdk.ui.getTheme(); // 'light' or 'dark'

// Use for conditional styling
const iconColor = cesdk.ui.getTheme() === 'dark' ? 'white' : 'black';

// Theme function is evaluated each time getTheme() is called
cesdk.ui.setTheme(() => new Date().getHours() >= 18 ? 'dark' : 'light');
const currentTheme = cesdk.ui.getTheme(); // Function is evaluated here

Signature#

getTheme(): Theme

setTheme()#

Sets the theme configuration.

This will immediately update the UI to reflect the new theme. Can be set to:

‘light’ or ‘dark’ for a specific theme
‘system’ to use the OS preference
A function that returns ‘light’ or ‘dark’ for dynamic theming

Parameters#

Parameter	Type	Description
`theme`	`ThemeConfig`	The theme configuration to set.

Returns#

void

Example#

// Set a specific theme
cesdk.ui.setTheme('dark');

// Use system preference
cesdk.ui.setTheme('system');

// Set theme based on custom logic
cesdk.ui.setTheme(() => {
  const hour = new Date().getHours();
  return hour >= 18 || hour < 6 ? 'dark' : 'light';
});

// Toggle between themes
const currentTheme = cesdk.ui.getTheme();
const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
cesdk.ui.setTheme(newTheme);

UI Layout#

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

Deprecated#

Use setComponentOrder({ in: 'ly.img.dock' }, order) instead.

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.

Deprecated#

Use getComponentOrder({ in: 'ly.img.dock' }) instead.

updateDockOrderComponent()#

Updates a component in the render order of the dock area.

This method finds a dock order component matching the provided matcher and updates it with the given component, ID, or updater function. The matcher can be a function or an object describing the component to match. The update can be a new ID, a partial object with updated properties, or a function that receives the current component and returns the updated one.

The update API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`DockOrderComponentId`>>	Function or object to match the component to update.
`update`		`DockOrderComponentId`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated dock order array.

Name	Type
`updated`	`number`
`order`	`OrderComponent`<`DockOrderComponentId`>[]

Deprecated#

Use updateOrderComponent({ in: 'ly.img.dock', match }, update) instead.

removeDockOrderComponent()#

Removes a component from the render order of the dock area.

This method finds a dock order component matching the provided matcher and removes it from the current order. The matcher can be a function or an object describing the component to match.

The remove API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`DockOrderComponentId`>>	Function or object to match the component to remove.
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated dock order array.

Name	Type
`removed`	`number`
`order`	`DockOrderComponent`[]

Deprecated#

Use removeOrderComponent({ in: 'ly.img.dock', match }) instead.

insertDockOrderComponent()#

Inserts a component into the render order of the dock area.

This method inserts a new dock order component before or after a component matching the provided matcher. The matcher can be a function or an object describing the component to match. The location can be ‘before’ or ‘after’.

The insert API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`DockOrderComponentId`>>	Function or object to match the component to insert relative to.
`component`		`DockOrderComponentId`
`location?`	`InsertOrderComponentLocation`	Where to insert the new component relative to the matched component (‘before’ or ‘after’).
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated dock order array.

Name	Type
`inserted`	`boolean`
`order`	(

Deprecated#

Use insertOrderComponent({ in: 'ly.img.dock', before/after }, component) instead.

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

Deprecated#

Use setComponentOrder({ in: 'ly.img.inspector.bar' }, order) instead.

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.

Deprecated#

Use getComponentOrder({ in: 'ly.img.inspector.bar' }) instead.

updateInspectorBarOrderComponent()#

Updates a component in the render order of the inspector bar.

This method finds an inspector bar order component matching the provided matcher and updates it with the given component, ID, or updater function. The matcher can be a function or an object describing the component to match. The update can be a new ID, a partial object with updated properties, or a function that receives the current component and returns the updated one.

The update API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`InspectorBarComponentId`>>	Function or object to match the component to update.
`update`		`InspectorBarComponentId`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated inspector bar order array.

Name	Type
`updated`	`number`
`order`	`OrderComponent`<`InspectorBarComponentId`>[]

Deprecated#

Use updateOrderComponent({ in: 'ly.img.inspector.bar', match }, update) instead.

removeInspectorBarOrderComponent()#

Removes a component from the render order of the inspector bar.

This method finds an inspector bar order component matching the provided matcher and removes it from the current order. The matcher can be a function or an object describing the component to match.

The remove API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`InspectorBarComponentId`>>	Function or object to match the component to remove.
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated inspector bar order array.

Name	Type
`removed`	`number`
`order`	`OrderComponent`<`InspectorBarComponentId`>[]

Deprecated#

Use removeOrderComponent({ in: 'ly.img.inspector.bar', match }) instead.

insertInspectorBarOrderComponent()#

Inserts a component into the render order of the inspector bar.

This method inserts a new inspector bar order component before or after a component matching the provided matcher. The matcher can be a function or an object describing the component to match. The location can be ‘before’ or ‘after’.

The insert API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`InspectorBarComponentId`>>	Function or object to match the component to insert relative to.
`component`		`InspectorBarComponentId`
`location?`	`InsertOrderComponentLocation`	Where to insert the new component relative to the matched component (‘before’ or ‘after’).
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated inspector bar order array.

Name	Type
`inserted`	`boolean`
`order`	(

Deprecated#

Use insertOrderComponent({ in: 'ly.img.inspector.bar', before/after }, component) instead.

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

Deprecated#

Use setComponentOrder({ in: 'ly.img.canvas.menu' }, order) instead.

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#

CanvasMenuOrderComponent[]

Array of component configurations defining the canvas menu order.

Deprecated#

Use getComponentOrder({ in: 'ly.img.canvas.menu' }) instead.

updateCanvasMenuOrderComponent()#

Updates a component in the render order of the canvas menu.

This method finds a canvas menu order component matching the provided matcher and updates it with the given component, ID, or updater function. The matcher can be a function or an object describing the component to match. The update can be a new ID, a partial object with updated properties, or a function that receives the current component and returns the updated one.

The update API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasMenuComponentId`>>	Function or object to match the component to update.
`update`		`CanvasMenuComponentId`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

An object containing the number of updated components and the updated canvas menu order array.

Name	Type
`updated`	`number`
`order`	`CanvasMenuOrderComponent`[]

Deprecated#

Use updateOrderComponent({ in: 'ly.img.canvas.menu', match }, update) instead.

removeCanvasMenuOrderComponent()#

Removes a component from the render order of the canvas menu.

This method finds a canvas menu order component matching the provided matcher and removes it from the current order. The matcher can be a function or an object describing the component to match.

The remove API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasMenuComponentId`>>	Function or object to match the component to remove.
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

An object containing the number of removed components and the updated canvas menu order array.

Name	Type
`removed`	`number`
`order`	`CanvasMenuOrderComponent`[]

Deprecated#

Use removeOrderComponent({ in: 'ly.img.canvas.menu', match }) instead.

insertCanvasMenuOrderComponent()#

Inserts a component into the render order of the canvas menu.

This method inserts a new canvas menu order component before or after a component matching the provided matcher. The matcher can be a function or an object describing the component to match. The location can be ‘before’ or ‘after’.

The insert API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasMenuComponentId`>>	Function or object to match the component to insert relative to.
`component`		`CanvasMenuComponentId`
`location?`	`InsertOrderComponentLocation`	Where to insert the new component relative to the matched component (‘before’ or ‘after’).
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated canvas menu order array.

Name	Type
`inserted`	`boolean`
`order`	(

Deprecated#

Use insertOrderComponent({ in: 'ly.img.canvas.menu', before/after }, component) instead.

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

Deprecated#

Use setComponentOrder({ in: 'ly.img.navigation.bar' }, order) instead.

updateNavigationBarOrderComponent()#

Updates a component in the render order of the navigation bar.

This method finds a navigation bar order component matching the provided matcher and updates it with the given component, ID, or updater function. The matcher can be a function or an object describing the component to match. The update can be a new ID, a partial object with updated properties, or a function that receives the current component and returns the updated one.

The update API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`NavigationBarComponentId`>>	Function or object to match the component to update.
`update`		`NavigationBarComponentId`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

An object containing the number of updated components and the updated navigation bar order array.

Name	Type
`updated`	`number`
`order`	`NavigationBarOrderComponent`[]

Deprecated#

Use updateOrderComponent({ in: 'ly.img.navigation.bar', match }, update) instead.

removeNavigationBarOrderComponent()#

Removes a component from the render order of the navigation bar.

This method finds a navigation bar order component matching the provided matcher and removes it from the current order. The matcher can be a function or an object describing the component to match.

The remove API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`NavigationBarComponentId`>>	Function or object to match the component to remove.
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

An object containing the number of removed components and the updated navigation bar order array.

Name	Type
`removed`	`number`
`order`	`NavigationBarOrderComponent`[]

Deprecated#

Use removeOrderComponent({ in: 'ly.img.navigation.bar', match }) instead.

insertNavigationBarOrderComponent()#

Inserts a component into the render order of the navigation bar.

This method inserts a new navigation bar order component before or after a component matching the provided matcher. The matcher can be a function or an object describing the component to match. The location can be ‘before’ or ‘after’.

The insert API can be used in different contexts (such as edit modes).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`NavigationBarComponentId`>>	Function or object to match the component to insert relative to.
`component`		`NavigationBarComponentId`
`location?`	`InsertOrderComponentLocation`	Where to insert the new component relative to the matched component (‘before’ or ‘after’).
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated navigation bar order array.

Name	Type
`inserted`	`boolean`
`order`	(

Deprecated#

Use insertOrderComponent({ in: 'ly.img.navigation.bar', before/after }, component) instead.

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.

Deprecated#

Use getComponentOrder({ in: 'ly.img.navigation.bar' }) instead.

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

Deprecated#

Use setComponentOrder({ in: 'ly.img.canvas.bar', at: position }, order) instead.

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.

Deprecated#

Use getComponentOrder({ in: 'ly.img.canvas.bar', at: position }) instead.

updateCanvasBarOrderComponent()#

Updates a component in the render order of the canvas bar.

This method finds a canvas bar order component matching the provided matcher and updates it with the given component, ID, or updater function. The matcher can be a function or an object describing the component to match. The update can be a new ID, a partial object with updated properties, or a function that receives the current component and returns the updated one.

The update API can be used in different contexts (such as edit modes and bar positions).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasBarComponentId`>>	Function or object to match the component to update.
`update`		`CanvasBarComponentId`
`position`	`"top"`	`"bottom"`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated canvas bar order array.

Name	Type
`updated`	`number`
`order`	`OrderComponent`<`CanvasBarComponentId`>[]

Deprecated#

Use updateOrderComponent({ in: 'ly.img.canvas.bar', at: position, match }, update) instead.

removeCanvasBarOrderComponent()#

Removes a component from the render order of the canvas bar.

This method finds a canvas bar order component matching the provided matcher and removes it from the current order. The matcher can be a function or an object describing the component to match.

The remove API can be used in different contexts (such as edit modes and bar positions).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasBarComponentId`>>	Function or object to match the component to remove.
`position`	`"top"`	`"bottom"`
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated canvas bar order array.

Name	Type
`removed`	`number`
`order`	`OrderComponent`<`CanvasBarComponentId`>[]

Deprecated#

Use removeOrderComponent({ in: 'ly.img.canvas.bar', at: position, match }) instead.

insertCanvasBarOrderComponent()#

Inserts a component into the render order of the canvas bar.

This method inserts a new canvas bar order component before or after a component matching the provided matcher. The matcher can be a function or an object describing the component to match. The location can be ‘before’ or ‘after’.

The insert API can be used in different contexts (such as edit modes and bar positions).

Parameters#

Parameter	Type	Description
`matcher`	`OrderComponentMatcher`<`OrderComponent`<`CanvasBarComponentId`>>	Function or object to match the component to insert relative to.
`component`		`CanvasBarComponentId`
`position`	`"top"`	`"bottom"`
`location?`	`InsertOrderComponentLocation`	Where to insert the new component relative to the matched component (‘before’ or ‘after’).
`orderContext?`	`OrderContext`	Optional context specifying which order to update.

Returns#

object

The updated canvas bar order array.

Name	Type
`inserted`	`boolean`
`order`	(

Deprecated#

Use insertOrderComponent({ in: 'ly.img.canvas.bar', at: position, before/after }, component) instead.

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

UI Scale Management#

getScale()#

Gets the resolved scale that is currently being used. If the scale configuration is a function, it is evaluated lazily and the result is returned.

Returns#

Scale

The resolved scale (‘normal’ or ‘large’).

Example#

// Get the actual scale being used
const scale = cesdk.ui.getScale(); // 'normal' or 'large'

// Use for conditional sizing
const fontSize = cesdk.ui.getScale() === 'large' ? '16px' : '14px';

// Scale function is evaluated each time getScale() is called
cesdk.ui.setScale(({ containerWidth }) => containerWidth < 768 ? 'large' : 'normal');
const currentScale = cesdk.ui.getScale(); // Function is evaluated here

Signature#

getScale(): Scale

setScale()#

Sets the scale configuration.

This will immediately update the UI to reflect the new scale. Can be set to:

‘normal’ or ‘large’ for a specific scale
A function that returns ‘normal’ or ‘large’ based on viewport properties

Parameters#

Parameter	Type	Description
`scale`	`ScaleConfig`	The scale configuration to set.

Returns#

void

Example#

// Set a specific scale
cesdk.ui.setScale('large');

// Set scale based on viewport
cesdk.ui.setScale(({ containerWidth, isTouch }) => {
  if (isTouch || containerWidth < 768) {
    return 'large';
  }
  return 'normal';
});

// Toggle between scales
const currentScale = cesdk.ui.getScale();
const newScale = currentScale === 'normal' ? 'large' : 'normal';
cesdk.ui.setScale(newScale);

Unified Component Order API#

setComponentOrder()#

Sets the rendering order of components in a UI area.

This unified method replaces area-specific methods like setDockOrder, setInspectorBarOrder, etc. It provides a consistent API for all UI areas.

Type Parameters#

Type Parameter
`A` extends `UIArea`

Parameters#

Parameter	Type	Description
`options`	`AnyUILocationOptions`<`A`>	Location options specifying which area to set. For canvas bar, requires `at` position.
`order`	`ComponentSpec`<`A`>[]	Array of component IDs or component objects defining the order.

Returns#

void

Example#

// Set dock order
cesdk.ui.setComponentOrder({ in: 'ly.img.dock' }, ['ly.img.spacer', 'my.button']);

// Set canvas bar order (requires position)
cesdk.ui.setComponentOrder(
  { in: 'ly.img.canvas.bar', at: 'top' },
  ['ly.img.settings.canvasBar']
);

// Set order with edit mode context
cesdk.ui.setComponentOrder(
  { in: 'ly.img.inspector.bar', when: { editMode: 'Text' } },
  ['ly.img.text.typeFace.inspectorBar', 'ly.img.text.bold.inspectorBar']
);

Signature#

setComponentOrder(options: AnyUILocationOptions<A>, order: ComponentSpec<A>[]): void

getComponentOrder()#

Gets the current rendering order of components in a UI area.

This unified method replaces area-specific methods like getDockOrder, getInspectorBarOrder, etc.

Type Parameters#

Type Parameter
`A` extends `UIArea`

Parameters#

Parameter	Type	Description
`options`	`AnyUILocationOptions`<`A`>	Location options specifying which area to get. For canvas bar, requires `at` position.

Returns#

OrderComponentFor<A>[]

Array of components in the specified area.

Example#

// Get dock order
const dockOrder = cesdk.ui.getComponentOrder({ in: 'ly.img.dock' });

// Get canvas bar order (requires position)
const canvasBarTop = cesdk.ui.getComponentOrder({ in: 'ly.img.canvas.bar', at: 'top' });

// Get order with edit mode context
const cropOrder = cesdk.ui.getComponentOrder({
  in: 'ly.img.inspector.bar',
  when: { editMode: 'Crop' }
});

Signature#

getComponentOrder(options: AnyUILocationOptions<A>): OrderComponentFor<A>[]

updateOrderComponent()#

Updates components matching a criteria in one or more UI areas.

This unified method replaces area-specific update methods. Supports glob patterns for both areas and component matching.

Canvas Bar Note: For ly.img.canvas.bar, if options.at is omitted, the update applies to BOTH top and bottom bars and results are combined.

Type Parameters#

Type Parameter
`A` extends `UIAreaSpecifier`

Parameters#

Parameter	Type	Description
`options`	`ComponentMatchOptions`<`A`>	Match options specifying where and what to update.
`update`	`UpdateSpec`<`UIArea`>	New ID, partial properties, or updater function.

Returns#

A extends UIArea ? UpdateResult<A<A>> : MultiAreaUpdateResult

For single area: UpdateResult. For multi-area: MultiAreaUpdateResult.

Example#

// Update by exact ID
cesdk.ui.updateOrderComponent(
  { in: 'ly.img.dock', match: 'ly.img.separator' },
  { key: 'my-separator' }
);

// Update by glob pattern
cesdk.ui.updateOrderComponent(
  { in: 'ly.img.dock', match: 'ly.img.*' },
  { disabled: true }
);

// Update using function
cesdk.ui.updateOrderComponent(
  { in: 'ly.img.inspector.bar', match: 'first' },
  (component) => ({ key: `${component.id}-modified` })
);

// Update across multiple areas
const results = cesdk.ui.updateOrderComponent(
  { in: '*', match: 'ly.img.separator' },
  { key: 'global-sep' }
);

Signature#

updateOrderComponent(options: ComponentMatchOptions<A>, update: UpdateSpec<UIArea>): A extends UIArea ? UpdateResult<A<A>> : MultiAreaUpdateResult

removeOrderComponent()#

Removes components matching a criteria from one or more UI areas.

This unified method replaces area-specific remove methods. Supports glob patterns for both areas and component matching.

Canvas Bar Note: For ly.img.canvas.bar, if options.at is omitted, the removal applies to BOTH top and bottom bars and results are combined.

Type Parameters#

Type Parameter
`A` extends `UIAreaSpecifier`

Parameters#

Parameter	Type	Description
`options`	`ComponentMatchOptions`<`A`>	Match options specifying where and what to remove.

Returns#

A extends UIArea ? RemoveResult<A<A>> : MultiAreaRemoveResult

For single area: RemoveResult. For multi-area: MultiAreaRemoveResult.

Example#

// Remove by exact ID
cesdk.ui.removeOrderComponent({ in: 'ly.img.dock', match: 'ly.img.separator' });

// Remove by position
cesdk.ui.removeOrderComponent({ in: 'ly.img.inspector.bar', match: 'last' });

// Remove by glob pattern
cesdk.ui.removeOrderComponent({ in: 'ly.img.dock', match: 'ly.img.*' });

// Remove from all areas
const results = cesdk.ui.removeOrderComponent({
  in: '*',
  match: 'ly.img.separator'
});

Signature#

removeOrderComponent(options: ComponentMatchOptions<A>): A extends UIArea ? RemoveResult<A<A>> : MultiAreaRemoveResult

insertOrderComponent()#

Inserts one or more components into a UI area at a specified position.

This unified method replaces area-specific insert methods. Supports inserting before, after, or at a specific index. When inserting multiple components, they are inserted in order at the specified position.

Canvas Bar Note: For ly.img.canvas.bar, options.at is required and must specify either ‘top’ or ‘bottom’.

Type Parameters#

Type Parameter
`A` extends `UIArea`

Parameters#

Parameter	Type	Description
`options`	`InsertComponentOptions`<`A`>	Insert options specifying where to insert.
`components`		`ComponentSpec`<`A`>

Returns#

InsertResult<A>

InsertResult with success status, count, and new order.

Example#

// Append single component to end (default)
cesdk.ui.insertOrderComponent({ in: 'ly.img.dock' }, 'my.button');

// Insert multiple components at once
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.dock', after: 'ly.img.spacer' },
  ['my.button.1', 'my.button.2', 'my.button.3']
);

// Insert before a component
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.dock', before: 'ly.img.separator' },
  'my.button'
);

// Insert after a component
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.inspector.bar', after: 'ly.img.fill.inspectorBar' },
  'my.fill.tool'
);

// Insert at specific position
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.dock', position: 'start' },
  ['first.button', 'second.button']
);

// Insert at index
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.dock', position: 2 },
  'my.third.button'
);

// Insert at negative index (from end)
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.dock', position: -1 },
  'my.before.last.button'
);

Signature#

insertOrderComponent(options: InsertComponentOptions<A>, components: ComponentSpec<A> | ComponentSpec<A>[]): InsertResult<A>

getOrderContext()#

Gets the active order context for a UI area.

Returns the full context including both settable properties (like view for the caption panel) and engine-derived properties (like editMode).

Type Parameters#

Type Parameter
`A` extends `UIArea`

Parameters#

Parameter	Type	Description
`options`	{ `in`: `A`; }	Location options specifying which area to get context for.
`options.in`	`A`	-

Returns#

OrderContextFor<A>

The full order context for the area, or undefined if no context has been set.

Example#

// Get caption panel context
const context = cesdk.ui.getOrderContext({ in: 'ly.img.caption.panel' });
// → { view: 'edit', editMode: 'Transform' } | undefined

// Get inspector bar context (editMode only, derived from engine)
const inspectorContext = cesdk.ui.getOrderContext({ in: 'ly.img.inspector.bar' });
// → { editMode: 'Crop' } | undefined

Signature#

getOrderContext(options: object): OrderContextFor<A>

setOrderContext()#

Sets the active order context for a UI area.

Only accepts settable properties (excludes base OrderContext properties like editMode which are derived from the engine). For the caption panel, this means you can set the view property.

Type Parameters#

Type Parameter
`A` extends `UIArea`

Parameters#

Parameter	Type	Description
`options`	{ `in`: `A`; }	Location options specifying which area to set context for.
`options.in`	`A`	-
`context`	`UIAreaContext`<`A`>	The context properties to set. Only settable properties are accepted.

Returns#

void

Example#

// Set caption panel to style view
cesdk.ui.setOrderContext(
  { in: 'ly.img.caption.panel' },
  { view: 'style' }
);

// Note: editMode cannot be set via this API - it's engine-derived
// Use cesdk.engine.editor.setEditMode('Crop') instead

Signature#

setOrderContext(options: object, context: UIAreaContext<A>): void