Skip to main content

Objects

This is the API reference for all canvas object types in Upmade. Every object consists of properties, computed properties and methods.

Base Object​

UpmadeBaseObject is the abstract base class for every object that can be placed on the canvas. All other object types listed below extend this class and inherit its properties, computed properties, and methods and extend them with their own specific functionality.

Properties​

PropertyTypeDescription
idstringUnique identifier
workspaceIdstringID of the workspace this object belongs to
xnumberX position in world coordinates
ynumberY position in world coordinates
translateXnumberWorld-space X translation
translateYnumberWorld-space Y translation
widthnumberWidth in world units
heightnumberHeight in world units
rotationnumberRotation in radians
opacitynumberOpacity (0–1)
zIndexnumberZ-order layer
scalenumberObject scale
backgroundColorThemeAwareColorBackground color
borderColorThemeAwareColorBorder color
borderWidthnumberBorder width
paddingnumberPadding
resizingbooleanWhether the object is currently being resized
markedForRemovalbooleanWhether the object is pending removal
userIdstringID of the user who created the object
namestringUser-facing name, shown as the title of its titlebar. Persisted and synced
isVisiblebooleanVisibility flag
isSelectedbooleanWhether the object is selected
isHoveredbooleanWhether the object is hovered
isMountedbooleanWhether the object is mounted to the DOM
isEditablebooleanWhether the object is in edit mode
isInteractivebooleanWhether the object responds to interaction
isResizablebooleanWhether the object can be resized. Persisted and synced. Combines with isResizable of the objectConfig prop: either one can forbid it
isRotatablebooleanWhether the object can be rotated. Persisted and synced. Combines with isRotatable of the objectConfig prop: either one can forbid it
isLoadingbooleanWhether the engine draws a loading placeholder over the object. Defaults to false. Persisted and synced
centerXnumberCenter X coordinate
centerYnumberCenter Y coordinate
totalWidthnumberWidth including padding and borders
totalHeightnumberHeight including padding and borders
boundingBoxUpmadeBoundingBoxAxis-aligned bounding box
rotatedBoundingBoxUpmadeBoundingBoxBounding box accounting for rotation
rotatedPolygonUpmadePolygonFour corners of the rotated rectangle
transformationMatrixDOMMatrixFull transformation matrix
rotationDegreesnumberRotation converted to degrees

Common Constructor Options​

The constructor of every object accepts the following options in addition to its own, for example in UpmadeShapeConfig or UpmadeTextConfig.

OptionTypeDescription
namestringUser-facing name, shown as the title of its titlebar
isLoadingbooleanWhether the object starts out with a loading placeholder. Defaults to false
const frame = new UpmadeShape({ translateX: 0, translateY: 0, width: 400, height: 240, name: 'Desktop' });

See Object Titlebar for details.

Loading State​

While isLoading is true, the engine draws a grey placeholder with a glare animation over the whole object. It follows the object's size and rotation, and the object can still be selected and moved, but its content can't be used until loading ends. Objects don't render loading content of their own. The look is set through the Loading Placeholder theme tokens.

const card = await this.editor.addObject(
new UpmadeShape({ translateX: 0, translateY: 0, width: 320, height: 200, isLoading: true }),
);

// later, once the content is ready
card?.setLoading(false);

Methods​

mount​

Mounts the object to a DOM element.

mount(element)

generateId​

Generates a new unique identifier.

generateId()

isInViewport​

Tests if the object is visible in the current viewport.

isInViewport()

centerInViewport​

Moves the object to the center of the current viewport.

centerInViewport()

update​

Notifies the store that the object was updated.

update()

setLoading​

Shows or hides the loading placeholder. Stores and syncs the change and rerenders. Does nothing if the value is unchanged.

setLoading(isLoading)

move​

Moves the object by the delta between two points.

move(startX, startY, endX, endY)

resize​

Resizes and repositions the object.

resize(x, y, width, height)

rotate​

Sets the rotation angle in radians.

rotate(value)

updatePosition​

Updates the object's translateX and translateY values.

updatePosition(x, y)

clone​

Creates a shallow copy of the object with the same id.

clone()

copy​

Creates an independent copy of the object with a new id.

copy()

serialize​

Converts the object to a plain serializable representation.

serialize()

deserialize​

Restores the object from serialized data.

deserialize(data)

isClass​

Checks whether the object's __class__ matches a class name.

isClass(className)

edit​

Handles edit actions and is overridden by editable object types.

edit(event)

hitTest​

Tests whether a world-coordinate point intersects this object.

hitTest(x, y)

hitTestPolygon​

Tests whether a polygon intersects this object.

hitTestPolygon(polygon)

Path​

UpmadePath represents a brush stroke rendered as an SVG path. It is created by the UpmadeBrushTool when the user draws a freehand stroke.

Properties​

PropertyTypeDescription
pointsnumber[][]Array of [x, y] coordinate pairs defining the path
dstringGenerated SVG path data string
strokeThemeAwareColorStroke color
strokeWidthnumberWidth of the stroke in pixels
lineSlacknumberAdditional padding for bounding box calculations
fillThemeAwareColorFill color
isDebugInfoVisiblebooleanWhether debug info is rendered for the path
isCompletedbooleanWhether the stroke has finished being drawn
viewBoxstringSVG viewBox attribute for local (object-relative) rendering

Line​

UpmadeLine represents a straight or curved line with configurable arrowheads at either end. UpmadeLineTool creates lines, which can snap their endpoints to anchors on other objects. Arrowheads support triangle, open, diamond, and circle styles.

Properties​

PropertyTypeDescription
startXnumberX coordinate of the start point
startYnumberX coordinate of the start point
endXnumberX coordinate of the end point
endYnumberX coordinate of the end point
controlXnumberX coordinate of the curve control point
controlYnumberX coordinate of the curve control point
strokeThemeAwareColorStroke color
strokeWidthnumberWidth of the stroke in pixels
startAnchorLineAnchorAnchor connection for the start point
endAnchorLineAnchorAnchor connection for the end point
arrowsLineArrowConfigArrow head configuration for start and end of line
isDebugInfoVisiblebooleanWhether debug info is rendered for the line
isCompletedbooleanWhether the line has finished being drawn
dstringGenerated SVG path data string (straight line or quadratic Bezier curve)
viewBoxstringSVG viewBox attribute string

Shape​

UpmadeShape represents a rectangle, ellipse, or triangle created by UpmadeShapeTool. Shapes can contain editable text, and the shapeType property determines their geometry.

Properties​

PropertyTypeDescription
shapeTypeShapeTypeRectangle, Ellipse, or Triangle
fillColorThemeAwareColorFill color
strokeColorThemeAwareColorStroke color
strokeWidthnumberWidth of the shape's stroke in pixels
fontFamilystringFont family for the shape's text content
fontSizenumberFont size for text content in points
fontColorThemeAwareColorFont color for text content
scaleFactornumberHorizontal scale factor for transformations
isEditingbooleanWhether the shape's text is currently being edited
editorEditorViewProseMirror editor instance for the shape's text
contentanySerialized ProseMirror document content
uneditedObjectUpmadeShapeSnapshot of the shape before editing started
viewBoxstringSVG viewBox using screen-space coordinates

Methods​

updateDimensions​

Recomputes world-space translateX and translateY from screen-space x and y values.

updateDimensions()

mountTextEditor​

Mounts the ProseMirror text editor to a DOM element.

mountTextEditor(element)

setContent​

Sets the text content from a serialized ProseMirror document.

setContent(content)

focus​

Focuses the text editor, optionally positioning the cursor at given coordinates.

focus(coords)

Text​

UpmadeText represents rich text on the canvas. It is created via the UpmadeTextTool and supports inline text editing.

Properties​

PropertyTypeDescription
fontFamilystringFont family name
fontSizenumberFont size in points
fontColorThemeAwareColorFont color
initialWidthnumberInitial width before scaling
initialHeightnumberInitial height before scaling
scaleFactornumberHorizontal scale factor for transformations
isDebugInfoVisiblebooleanWhether debug info is rendered for the text object
isEditingbooleanWhether the text is currently being edited
isNewlyCreatedbooleanWhether the text object was just created and not yet edited
editorEditorViewProseMirror editor instance
contentanySerialized ProseMirror document content
uneditedObjectUpmadeTextSnapshot of the text object before editing started
rowsnumberNumber of text rows
isEmptybooleanWhether the editor is empty or contains only whitespace

Methods​

setContent​

Sets the text content from a serialized ProseMirror document.

setContent(content)

createEditor​

Creates and configures a new ProseMirror editor instance.

createEditor()

adjustSizeOnInput​

Recalculates width and height based on the current content.

adjustSizeOnInput()

focus​

Focuses the text editor, optionally positioning the cursor at given coordinates.

focus(coords)

Image​

UpmadeImage represents a raster image placed on the canvas by UpmadeImageTool. It supports resizing while preserving the image's aspect ratio.

Properties​

PropertyTypeDescription
assetIdstringStable asset identifier used to resolve the image bytes
mimeTypestringMIME type of the referenced asset
srcstringLegacy inline data URL (deprecated, use assetId)
maxWidthnumberMaximum width in pixels
maxHeightnumberMaximum height in pixels
maxCompressionSizenumberMaximum size used when compressing the image
resolvedSrcstringURL resolved from the asset storage layer (not persisted)
loadStateUpmadeAssetLoadStateCurrent load state of the referenced asset (not persisted)
maxLoadAttemptsnumberMaximum number of definitive resolution failures before giving up
loadAttemptsnumberNumber of definitive resolution failures so far (not persisted)
maxTransientRetryDurationMsnumberMaximum time to keep retrying transient failures
transientRetryStartedAtnumberTimestamp of the first transient failure in the current retry chain

Methods​

ensureResolved​

Triggers idempotent resolution of the referenced asset.

ensureResolved()

Group​

UpmadeGroup permanently groups multiple objects so that they can be manipulated as a single unit. Groups may be nested. Selecting a child selects its group. Their children move, resize, and rotate as a unit.

Properties​

PropertyTypeDescription
childIdsstring[]IDs of the child objects within this group
childrenUpmadeBaseObject[]The actual child objects resolved from the store
lengthnumberNumber of children in this group

Methods​

addChild​

Adds a child object to this group.

addChild(object)

removeChild​

Removes a child object from this group by id.

removeChild(objectId)

ungroup​

Returns all children as top-level objects.

ungroup()

finalize​

Refreshes the bounding box and snapshots after children are positioned.

finalize()

refreshBoundingBox​

Recalculates the group's bounding box based on its children.

refreshBoundingBox()

Static Methods​

createFromObjects​

Creates a group from an array of existing objects.

createFromObjects(core, objects)

findParentGroup​

Finds the parent group that contains the given object as a direct child.

findParentGroup(core, objectId)

collectDescendantIds​

Recursively collects the ids of all descendants of a group.

collectDescendantIds(group)

Dynamic Object​

UpmadeDynamicObject represents a user-defined custom HTML element on the canvas. It can embed arbitrary HTML content and participates in selection, movement, and z-ordering like any other object.

Properties​

PropertyTypeDescription
elementHTMLElementThe HTML element rendered on the canvas
rendererKeystringIdentifier for a registered renderer (e.g. 'angular-component', 'react-default')
rendererDataunknownCustom data payload passed to the renderer

Methods​

setIsInteractive​

Updates interactivity state for the embedded HTML content.

setIsInteractive(isInteractive)

hasFocusedInputElement​

Returns true when a text-input-like element inside this object currently has focus.

hasFocusedInputElement()

Iframe Object​

UpmadeIframeObject renders HTML, CSS, and JavaScript in a sandboxed iframe on the canvas. See Rendering iFrames and Interacting with iFrame Content. The editor's object element methods call the element methods below by object ID.

Properties​

PropertyTypeDescription
contentUpmadeIframeContentThe html, css, and script of the page
stateRecord<string, unknown>Serializable state shared with the page as upmade.state
titlestringTitle of the iframe element
sandboxstring[]Sandbox tokens of the iframe. Defaults to ['allow-scripts']
isElementPickingbooleanWhether the object is picking elements (not persisted)

Methods​

setContent​

Replaces the content and reloads the page.

setContent(content)

setState​

Replaces the state and sends it to the page.

setState(state)

setElementPicking​

Turns element picking on or off. While picking, a click on an element of the page picks it instead of reaching the page.

setElementPicking(enabled, options)

setElementHighlights​

Replaces the element highlights drawn inside the page. Pass an empty array to remove them.

setElementHighlights(highlights)

getElementHighlights​

Returns the current element highlights.

getElementHighlights()

queryElements​

Describes the elements of the page that match a CSS selector, in document order, with their state (for example disabled, checked, or focused). The second argument is the limit, or options: limit defaults to 100 and can be at most 500, interactiveOnly: true keeps only elements a user can interact with (buttons, links, form fields, elements with an interactive ARIA role, and elements that show a pointer cursor), and includeValues: true adds the value of form fields, never of password fields.

queryElements(selector, limitOrOptions)

interactWithElement​

Performs an interaction on the first element of the page that matches a CSS selector, as a user would: a click, hover, fill, check, key press, or scroll (see UpmadeObjectElementInteraction). The page scrolls the element into view and checks that it is visible, enabled, and not covered, then dispatches the events of the interaction. It works whether or not the object is selected. With { trial: true }, only the checks run. It resolves with completed: false and a reason when the interaction can't be performed, also when the object isn't mounted or the page doesn't respond, and rejects only for an invalid selector or interaction. Agents use it through interactWithElement().

interactWithElement(selector, interaction, options)
const result = await iframe.interactWithElement('#play', { type: 'click' });
if (!result.completed) console.warn(result.reason, result.message);

The events are not trusted (isTrusted is false) and carry no user activation, so browser APIs that need a user gesture, such as audio playback, fullscreen, or the clipboard, may refuse to work from them.

trackElement​

Starts reporting the visible position of the first element that matches a selector. Calls are counted, so each call needs a matching untrackElement. An agent's cursor uses this to follow an element it points at (agent.moveTo({ objectId, selector })).

trackElement(selector)

untrackElement​

Undoes one trackElement call for a selector.

untrackElement(selector)

getTrackedElementRect​

Returns the last known visible bounding box of a tracked element in content coordinates, or null if it hasn't been seen yet.

getTrackedElementRect(selector)

contentToObjectLocal​

Converts a point in content coordinates to world units in the object's local, unrotated space, relative to its top-left corner.

contentToObjectLocal(point)

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.