Skip to main content

Editor

The <UpmadeEditor> is the high-level, full-featured whiteboard component. It wraps <UpmadeEngine> and adds a toolbar, utility panel, context menus, dialogs, and workspace management.

All methods are async and return Promises. The editor exposes all the same methods as the engine.

General​

Props​

PropertyTypeDefaultDescription
scaleMaxnumberABSOLUTE_SCALE_MAXMaximum zoom scale allowed
scaleMinnumberABSOLUTE_SCALE_MINMinimum zoom scale allowed
lockDrawingScalebooleantrueWhen true, objects are drawn at a fixed visual size regardless of zoom
viewportBoundaryLeftnumber-InfinityLeft boundary in world coordinates
viewportBoundaryRightnumberInfinityRight boundary in world coordinates
viewportBoundaryTopnumber-InfinityTop boundary in world coordinates
viewportBoundaryBottomnumberInfinityBottom boundary in world coordinates
toolbarItemsUpmadeToolbarItem[]Default toolbarToolbar items (selection, brush, line, eraser, text, shape, image, config)
globalContextMenuItemsContextMenuItem[]Paste, Select AllContext menu when right-clicking the canvas background
objectContextMenuItemsContextMenuItem[]Copy, Paste, Order, Align, Group, DeleteContext menu when right-clicking a selected object
customSvgIconsRecord<string, string>Custom SVG icon definitions by name
isToolbarVisiblebooleantrueShow/hide the toolbar
isUtilityPanelVisiblebooleantrueShow/hide the utility panel (undo/redo, zoom)
isWatermarkVisiblebooleantrueShow/hide the upmade.io watermark
syncConfigUpmadeSyncConfigundefinedSync provider configuration
workspacesUpmadeWorkspace[]undefinedOptional authoritative workspace catalog for this editor instance. Provider-only workspaces are hidden but not deleted.

Events​

EventPayload TypeDescription
isReadyHTMLElementEmitted when the editor is fully initialized
objectsChangeUpmadeBaseObject[]Emitted when objects are added, removed, or modified
objectsAddedObjectsAddedEventEmitted when objects are added. source is set when an agent made the change.
objectsRemovedObjectsRemovedEventEmitted when objects are removed. source is set when an agent made the change.
objectsUpdatedObjectsUpdatedEventEmitted when objects are updated. source is set when an agent made the change.
undoStateChangeUpmadeUndoStateEmitted when undo/redo availability changes
themeChangeThemeNameEmitted when the theme changes
viewportChangeUpmadeViewportStateEmitted on pan, zoom, or resize

Methods​

beginSceneBootstrap​

Starts a scene bootstrap phase by hiding the scene immediately.

beginSceneBootstrap(): Promise<void>

endSceneBootstrap​

Ends the scene bootstrap phase.

endSceneBootstrap(): Promise<void>

UI Elements​

Props​

PropertyTypeDescription
chatBoxChipsUpmadeChatBoxChip[]Chips shown above the chat box, e.g. the selected object or the element the next prompt refers to. Up to three share one row, the rest show as "+N more". The editor never changes them: pass a new array, for example when chatChipRemove fires.
chatSessionUpmadeChatSessionA chat session the chat box sends its prompts to, with chatBoxChips as what they refer to. While it runs, the chat box shows its progress and its stop button stops it.
chatBoxMode'collapsed' | 'expanded'Initial chat box mode. A collapsed chat box expands automatically when its text overflows one row.
cursorTargetHTMLElementElement used as cursor target. Defaults to the editor container if omitted.
customSvgIconsUpmadeSvgIconMapCustom SVG icon definitions.
globalContextMenuItemsContextMenuItem[]Context menu items shown on the canvas background.
isChatBoxLoadingbooleanShows the chat box progress ring and turns its send button into a stop button. A bound chatSession does this by itself while it runs.
isChatBoxVisiblebooleanShows the chat box instead of the toolbar.
isMoreMenuVisiblebooleanControls visibility of the More menu.
isToolbarVisiblebooleanControls toolbar visibility.
isUtilityPanelVisiblebooleanControls utility panel visibility.
isWatermarkVisiblebooleanShow or hide the upmade.io watermark (default true). Keeping it visible helps support the project.
isWorkspaceManagerVisiblebooleanControls workspace manager visibility.
isZoomPanelVisiblebooleanControls zoom panel visibility.
moreMenuItemsIUpmadeMenuItem[]Custom entries for the More dropdown menu.
objectContextMenuItemsContextMenuItem[]Context menu items shown for selected objects.

Events​

EventPayload TypeDescription
chatChipRemoveUpmadeChatBoxChipEmitted with the chat box chip whose remove button the user activated. The chip stays until chatBoxChips no longer contains it.
chatStopvoidEmitted when the user stops the current chat response. A bound chatSession is stopped too.
chatSubmitstringEmitted with the chat box text when the user submits it. With a chatSession, the prompt is sent to it unless a listener calls preventDefault(). While a response runs, Enter keeps the text in the box.

UpmadeChatBoxChip describes one chip. Its texts are shown verbatim, they are not translated:

PropertyTypeDescription
idstringUnique, stable identifier, e.g. the id of the referenced object.
labelstringMain text, shown bold, e.g. the referenced object's name.
detailstring (optional)A narrower part of the label, shown after ›, e.g. the element picked inside the object.
hintstring (optional)Muted text after the label and detail, e.g. what the user can do next.
iconUpmadeIconName (optional)Registered icon shown before the label, e.g. 'cursor'.
objectIdstring (optional)The object the chip refers to. A chat session tells the model about it. Not shown.
selectorstring (optional)CSS selector of the element inside the object the chip refers to. A chat session tells the model about it. Not shown.

Methods​

openContextMenu​

Opens a context menu at screen coordinates: openContextMenu(options: { x: number; y: number; objectId?: string }): Promise<void>.

openWorkspaceManagerMenu​

Opens the workspace manager menu: openWorkspaceManagerMenu(): Promise<void>.

openMoreMenu​

Opens the More menu: openMoreMenu(): Promise<void>.

hideContextMenu​

Hides the active context menu: hideContextMenu(): Promise<void>.

getDisplayableShortcuts​

Returns registered shortcuts without their actions or conditions: getDisplayableShortcuts(): Promise<Omit<UpmadeShortcut, "action" | "condition">[]>.

triggerNotification​

Shows a UI notification: triggerNotification(notification: Omit<UpmadeNotification, "id"> & Partial<Pick<UpmadeNotification, "id" | "timestamp">>): Promise<void>.

Object​

Props​

PropertyTypeDescription
objectConfigUpmadeObjectConfigConfigures how objects behave, in one place for all objects: which objects get a titlebar, and which can be rotated or resized. Each option is a boolean or a function of the object. See Configuring Objects.

Methods​

addObject​

Adds a new object to the canvas. The object is automatically assigned an ID, core reference, and z-index. It plays the theme's appear animation, see Object Appear.

addObject<T extends UpmadeBaseObject>(object: T): Promise<T | null>

addObjects​

Adds multiple objects in one undo step and render cycle. The objects appear one after another, in their order.

addObjects<T extends UpmadeBaseObject>(objects: T[]): Promise<T[]>

removeObject​

Removes an object from the canvas.

removeObject<T extends UpmadeBaseObject>(object: T): Promise<T | null>

removeObjects​

Removes multiple objects in one batch operation.

removeObjects<T extends UpmadeBaseObject>(objects: T[]): Promise<T[]>

updateObject​

Updates properties of an existing canvas object.

updateObject<T extends UpmadeBaseObject>(object: T, updatedProperties: Partial<T>): Promise<T | null>

getObjectById​

Retrieves a canvas object by its unique ID.

getObjectById<T extends UpmadeBaseObject>(id: string): Promise<T | null>

getAllObjects​

Returns all objects on the canvas across all layers.

getAllObjects<T extends UpmadeBaseObject>: Promise<T[]>

findObjects​

Returns all objects matching the given predicate. Excludes internal selection-related objects.

findObjects<T extends UpmadeBaseObject>(predicate: (obj: UpmadeBaseObject) => boolean): Promise<T[]>

getObjectsTotalCount​

Returns the total number of objects on the canvas.

getObjectsTotalCount: Promise<number>

getObjectsInViewport​

Returns all objects currently visible within the viewport bounds.

getObjectsInViewport: Promise<UpmadeBaseObject[]>

Selection​

getSelectedObjects​

Returns the currently selected objects. Returns an empty array if nothing is selected.

getSelectedObjects: Promise<UpmadeBaseObject[]>

selectObjects​

Programmatically selects the given objects. Switches to the selection tool automatically.

selectObjects(objects: UpmadeBaseObject[]): Promise<void>

selectAllObjectsInViewport​

Selects all objects currently visible in the viewport. Switches to the selection tool automatically.

selectAllObjectsInViewport: Promise<void>

clearSelection​

Deselects all currently selected objects.

clearSelection: Promise<void>

triggerSelectionChange​

Manually triggers the objectsSelectionChange event.

triggerSelectionChange: Promise<void>

Viewport & Navigation​

getViewport​

Returns the current viewport state including position, scale, and dimensions.

getViewport: Promise<UpmadeViewportState>

setViewport​

Sets the viewport to center on the given world coordinates at the specified scale.

setViewport(x: number, y: number, scale: number): Promise<void>

panTo​

Pans the viewport to center on the given world coordinates without changing the scale.

panTo(x: number, y: number): Promise<void>

panToObject​

Pans to an object without changing scale.

panToObject(object: UpmadeBaseObject): Promise<void>

zoomTo​

Zooms the viewport to the given scale. Optionally centers on a world point; if omitted, zooms around the viewport center.

zoomTo(scale: number, worldX?: number, worldY?: number): Promise<void>

zoomIn​

Zooms in by one configured step.

zoomIn(): Promise<void>

zoomOut​

Zooms out by one configured step.

zoomOut(): Promise<void>

centerObjectInViewport​

Pans and zooms the viewport to center on the given object.

centerObjectInViewport(object: UpmadeBaseObject): Promise<UpmadeBaseObject>

centerObjects​

Moves the supplied objects so their combined bounds are centered in the viewport.

centerObjects(objects: UpmadeBaseObject[]): Promise<void>

centerAllObjects​

Moves all objects so their combined bounds are centered in the viewport.

centerAllObjects(): Promise<void>

backToContent​

Pans and zooms the viewport to fit the nearest content, with padding. Useful when the user has panned away from all objects.

backToContent: Promise<boolean>

Returns true if content was found and the viewport was adjusted, false otherwise.

screenToWorld​

Converts screen-relative pixel coordinates to world coordinates.

screenToWorld(x: number, y: number): Promise<{ x: number; y: number }>

worldToScreen​

Converts world coordinates to screen-relative pixel coordinates.

worldToScreen(x: number, y: number): Promise<{ x: number; y: number }>

Workspace​

setActiveWorkspace​

Switches the active workspace shown in the editor by ID.

setActiveWorkspace(id: string): Promise<void>

createWorkspace​

Creates a new workspace and emits a workspacesChange event. Accepts an UpmadeWorkspace instance.

createWorkspace(workspace: UpmadeWorkspace): Promise<UpmadeWorkspace | null>

updateWorkspace​

Applies a workspace as declared and emits a workspacesChange event. Metadata and viewport are always applied. When workspace.objects is set it is treated as the complete desired object set: objects are matched by ID, unknown IDs are added, known IDs are updated, and objects missing from the list are removed. Leave objects undefined to keep the current objects, or pass [] to remove them all. Updating the objects of a workspace that is not currently active requires a configured sync provider.

updateWorkspace(workspace: UpmadeWorkspace): Promise<void>

deleteWorkspace​

Deletes a workspace and emits a workspacesChange event.

deleteWorkspace(workspace: UpmadeWorkspace): Promise<void>

getWorkspaces​

Returns all available workspaces.

getWorkspaces: Promise<UpmadeWorkspace[]>

getActiveWorkspace​

Returns the currently active workspace.

getActiveWorkspace: Promise<UpmadeWorkspace>

loadSharedWorkspace​

Loads a shared workspace by identifier.

loadSharedWorkspace(workspaceId: string): Promise<void>

Tool Management​

registerTool​

Registers a new drawing tool with the engine.

registerTool(
toolName: string,
toolClass: any,
toolConfig?: UpmadeBrushToolConfig | UpmadeLineToolConfig | UpmadeTextToolConfig | UpmadeShapeToolConfig
): Promise<UpmadeBaseTool>

setActiveTool​

Switches the active drawing tool. Deactivates the current tool and clears any selection.

setActiveTool(toolName: string): Promise<void>

disable​

Disables all user interaction with the engine (pointer, keyboard, etc.).

disable: Promise<void>

enable​

Re-enables user interaction after a call to disable.

enable: Promise<void>

Clipboard & Editing​

copy​

Copies the currently selected objects to the internal clipboard.

copy: Promise<void>

cut​

Cuts selected objects to the clipboard.

cut(): Promise<void>

paste​

Pastes previously copied objects at the specified world coordinates.

paste(x: number, y: number): Promise<void>

delete​

Deletes the currently selected objects from the canvas.

delete: Promise<void>

Ordering​

bringForward​

Moves an object one layer forward in the z-order, past the next layer above it. If omitted, applies to the current selection and moves each selected layer. A group is one layer, so all of its children move together; a grouped object moves within its group.

bringForward(object?: UpmadeBaseObject): Promise<void>

sendBackward​

Moves an object one layer backward in the z-order, past the next layer below it. If omitted, applies to the current selection and moves each selected layer. A group is one layer, so all of its children move together; a grouped object moves within its group.

sendBackward(object?: UpmadeBaseObject): Promise<void>

bringToFront​

Moves an object to the very front of the z-order. If omitted, applies to the current selection, keeping the relative order of the selected layers. A group moves together with all of its children; a grouped object moves to the front of its group.

bringToFront(object?: UpmadeBaseObject): Promise<void>

sendToBack​

Moves an object to the very back of the z-order. If omitted, applies to the current selection, keeping the relative order of the selected layers. A group moves together with all of its children; a grouped object moves to the back of its group.

sendToBack(object?: UpmadeBaseObject): Promise<void>

Alignment​

alignObjects​

Aligns the currently selected objects according to the specified alignment.

alignObjects(alignment: UpmadeAlignment): Promise<void>

Alignment values: StartHorizontal, CenterHorizontal, EndHorizontal, StartVertical, CenterVertical, EndVertical.


Grouping​

group​

Creates a group (UpmadeGroup) from the given objects. Requires at least two objects. They become one layer at the position of the topmost object, in a single undoable step. Resolves to the created group, or null when fewer than two objects could be grouped. To group the current selection, pass await getSelectedObjects(). See the engine's group for details.

group(objects: UpmadeBaseObject[]): Promise<UpmadeGroup | null>

ungroup​

Ungroups the given groups. Their children become individual objects again and keep their stacking order, in a single undoable step. Resolves to the extracted children. To ungroup the current selection, pass the UpmadeGroup objects from await getSelectedObjects(). See the engine's ungroup for details.

ungroup(groups: UpmadeGroup[]): Promise<UpmadeBaseObject[]>

Undo & Redo​

undo​

Undoes the last action.

undo: Promise<void>

redo​

Redoes the last undone action.

redo: Promise<void>

Export & Import​

getScreenshot​

Captures a screenshot of the current viewport as a data URL.

getScreenshot(format?: 'png' | 'svg'): Promise<string>

exportViewportAsPng​

Exports the current viewport as a PNG file and triggers a browser download.

exportViewportAsPng: Promise<void>

exportViewportAsSvg​

Exports the current viewport as an SVG file and triggers a browser download.

exportViewportAsSvg: Promise<void>

canExportSelectedObjectAs​

Checks whether the selected object supports a format.

canExportSelectedObjectAs(format: UpmadeExportFormat): Promise<boolean>

exportSelectedObject​

Exports the selected object in the requested format.

exportSelectedObject(format: UpmadeExportFormat): Promise<void>

getSelectedObjectSupportedExportFormats​

Returns export formats supported by the selected object.

getSelectedObjectSupportedExportFormats(): Promise<UpmadeExportFormat[]>

downloadAsJson​

Downloads the canvas state as a JSON file. Use the optional filename directly.

downloadAsJson(filename?: string): Promise<void>

importFromFile​

Triggers a local file selector, parsing the user's selected file to import objects.

importFromFile(): Promise<void>

loadObjectsFromJson​

Hydrates the canvas with a serialized JSON string containing objects.

loadObjectsFromJson(json: string): Promise<number>

Theming​

Props​

PropertyTypeDescription
customFontsUpmadeFontMapRegisters fonts for runtime rendering and text-tool usage.
themeThemeCodeCurrent active theme.
themesUpmadeTheme[]Available theme definitions.

Events​

EventPayload TypeDescription
themeChangeThemeCodeEmitted when the active theme changes.

Methods​

registerFonts​

Registers custom fonts for runtime rendering and text-tool usage.

registerFonts(fonts: UpmadeFontMap): Promise<void>

Localization​

Props​

PropertyTypeDescription
fallbackLocaleLocaleCodeLocale used to resolve terms missing from the active locale.
localeLocaleCodeCurrent locale code used by the editor.
localesUpmadeLocale[]Available locale definitions with optional term overrides.

Events​

EventPayload TypeDescription
localeChangeLocaleCodeEmitted when the active locale changes.

Methods​

registerLocales​

Registers locale definitions: registerLocales(locales: UpmadeLocale[]): Promise<void>.

getAvailableLocales​

Returns available locale codes: getAvailableLocales(): Promise<LocaleCode[]>.

getLocale​

Returns the active locale: getLocale(): Promise<LocaleCode>.

setLocale​

Sets the active locale: setLocale(code: LocaleCode): Promise<void>.

t​

Resolves a localized term: t(key: UpmadeTermKey, vars?: UpmadeTermVars): Promise<string>.

User Management​

Props​

PropertyTypeDescription
userIUpmadeUserCurrent authenticated user for awareness and collaboration state.
loginConfigUpmadeLoginConfigLogin dialog provider configuration.

Events​

EventPayload TypeDescription
loginLoginEventEmitted when login is triggered from the authentication dialog.
logoutvoidEmitted when logout is triggered from the editor UI.

Methods​

openLoginDialog​

Opens the configured login dialog: openLoginDialog(): Promise<void>.

setLoginLoading​

Sets a provider's loading state: setLoginLoading(provider: string | null): Promise<void>.

Collaboration​

Props​

PropertyTypeDescription
activeUsersIUpmadeUser[]Other users currently in the session.
syncConfigUpmadeSyncConfigReal-time collaboration provider configuration.

Events​

EventPayload TypeDescription
awarenessChangeAwarenessStateMapEmitted when collaborative awareness state changes.

Methods​

reinitSync​

Reinitializes the active synchronization provider connection.

reinitSync(): Promise<void>

Agents​

Agents are participants on the canvas that are driven by code, for example an AI assistant. Each agent is a UpmadeAgent with its own cursor, actions, and undo history. See Agents for a guide. When the editor shares presence, collaborators see its agents, and it shows theirs; see Collaboration.

Props​

PropertyTypeDescription
isAgentAvatarsVisiblebooleanWhether the avatar stack shows the agents, those of this editor and those of collaborators, after the active users (default true). Each agent has a bot badge, a ring while it works, and its status in the tooltip.

Events​

EventPayload TypeDescription
agentsChangeUpmadeAgentsChangeEventEmitted when agents are added or removed, or when their name, color, avatar, status, visibility, or activity changes, in this editor or in the editor of a collaborator. Lists the agents of this editor first, then the agents of collaborators (isRemote: true). Never emitted for plain cursor motion.

Methods​

addAgent​

Adds an agent and shows its cursor. Adding the same agent again does nothing. An agent belongs to one editor at a time; an agent of an editor that was removed from the page moves here. Call it after the editor emitted isReady. Rejects for a value that is not an UpmadeAgent, for a second agent with the same ID, and for an agent of another editor.

addAgent(agent: UpmadeAgent): Promise<UpmadeAgent>

removeAgent​

Removes an agent, given the agent or its ID: its running action is rolled back, its queued actions resolve with 'agent-removed', and its cursor and history are dropped. The agent can be added again. Resolves with false if the agent was not added.

removeAgent(agent: UpmadeAgent | string): Promise<boolean>

getAgent​

Returns an agent added to this editor by its ID, or null if there is none. Agents of collaborators are never returned; see getRemoteAgents.

getAgent(id: string): Promise<UpmadeAgent | null>

getAgents​

Returns the agents added to this editor.

getAgents(): Promise<UpmadeAgent[]>

getRemoteAgents​

Returns the agents of collaborators, as they share them through presence. They are descriptions, not UpmadeAgent objects, and cannot be controlled from here. Empty without a sync provider that shares presence. See UpmadeRemoteAgentPresence.

getRemoteAgents(): Promise<UpmadeRemoteAgentPresence[]>

Object Titlebar​

Props​

PropertyTypeDescription
objectTitlebarUpmadeObjectTitlebarConfigContent of the titlebar rendered above every object for which objectConfig.hasTitlebar is true. The same configuration applies to all objects. Leave unset to disable titlebars. See Object Titlebar.

Events​

EventPayload TypeDescription
objectTitlebarActionUpmadeObjectTitlebarActionEventEmitted when a button in an object titlebar is clicked or a menu item of a titlebar menu is selected, in addition to calling the optional action callback of the button or menu item.

Methods​

No titlebar-specific methods. Titlebar menus are rendered by the editor itself. Use updateObject to change the name of an existing object.


Object Elements​

Elements inside the content of objects such as UpmadeIframeObject. See Interacting with iFrame Content.

Props​

No object-element-specific props.

Events​

EventPayload TypeDescription
objectElementHoverUpmadeObjectElementHoverEventEmitted when the mouse or pen pointer moves onto another element inside the content of a selected object, such as an iframe object, and with element: null when it leaves the content or the object is deselected.
objectElementClickUpmadeObjectElementClickEventEmitted when the user clicks an element inside the content of a selected object. The click works as usual.
objectElementPickUpmadeObjectElementPickEventEmitted when the user picks an element inside an object that is picking elements. The click doesn't reach the content. See setObjectElementPicking.

Methods​

setObjectElementPicking​

Turns element picking on or off for an object whose content has elements, such as an iframe object. While picking, the element under the pointer is highlighted, and a press or click emits objectElementPick instead of reaching the content. Picking works while the object is selected and stays on until it is turned off. selector limits picking to the closest matching ancestor of the element under the pointer, color sets the highlight color.

setObjectElementPicking(objectId: string, enabled: boolean, options?: UpmadeObjectElementPickingOptions): Promise<void>

highlightObjectElements​

Highlights elements inside an object's content, replacing the object's previous highlights. Each entry is { selector, color?, label? }, and every element that matches its selector is highlighted, up to 100 per selector. Highlights are local: they are neither saved nor shown to collaborators.

highlightObjectElements(objectId: string, highlights: UpmadeObjectElementHighlight[]): Promise<void>

clearObjectElementHighlights​

Removes the element highlights of an object, or of all objects when objectId is omitted.

clearObjectElementHighlights(objectId?: string): Promise<void>

queryObjectElements​

Describes the elements inside an object's content that match a CSS selector, in document order. Each result has a selector that can be used to highlight the element or point an agent's cursor at it (agent.moveTo({ objectId, selector }), see UpmadeAgenticTarget). limit defaults to 100 and can be at most 500. The object must be mounted, which it is while it is in or near the viewport. Rejects when the content does not answer within 3 seconds, or within 15 seconds while it is still loading.

queryObjectElements(objectId: string, selector: string, limit?: number): Promise<UpmadeObjectElementInfo[]>

All object element methods reject for invalid selectors and for objects that don't exist or have no content elements.

Support us

Upmade is an MIT-licensed open source project. If you like the idea of a framework-agnostic infinite canvas library and want to support our work, leave us a star or consider becoming a sponsor.