Editor
The <kritzel-editor> is the high-level, full-featured whiteboard component. It wraps <kritzel-engine> and adds a toolbar, utility panel, context menus, dialogs, and workspace management.
Props
| Property | Type | Default | Description |
|---|---|---|---|
| scaleMax | number | ABSOLUTE_SCALE_MAX | Maximum zoom scale allowed |
| scaleMin | number | ABSOLUTE_SCALE_MIN | Minimum zoom scale allowed |
| lockDrawingScale | boolean | true | When true, objects are drawn at a fixed visual size regardless of zoom |
| viewportBoundaryLeft | number | -Infinity | Left boundary in world coordinates |
| viewportBoundaryRight | number | Infinity | Right boundary in world coordinates |
| viewportBoundaryTop | number | -Infinity | Top boundary in world coordinates |
| viewportBoundaryBottom | number | Infinity | Bottom boundary in world coordinates |
| controls | KritzelToolbarControl[] | Default toolbar | Toolbar items (selection, brush, line, eraser, text, shape, image, config) |
| globalContextMenuItems | ContextMenuItem[] | Paste, Select All | Context menu when right-clicking the canvas background |
| objectContextMenuItems | ContextMenuItem[] | Copy, Paste, Order, Align, Group, Delete | Context menu when right-clicking a selected object |
| customSvgIcons | Record<string, string> | Custom SVG icon definitions by name | |
| isControlsVisible | boolean | true | Show/hide the toolbar |
| isUtilityPanelVisible | boolean | true | Show/hide the utility panel (undo/redo, zoom) |
| syncConfig | KritzelSyncConfig | undefined | Sync provider configuration |
Events
| Event | Payload Type | Description |
|---|---|---|
| isReady | HTMLElement | Emitted when the editor is fully initialized |
| objectsChange | KritzelBaseObject[] | Emitted when objects are added, removed, or modified |
| objectsAdded | ObjectsAddedEvent | Emitted when objects are added |
| objectsRemoved | ObjectsRemovedEvent | Emitted when objects are removed |
| objectsUpdated | ObjectsUpdatedEvent | Emitted when objects are updated |
| undoStateChange | KritzelUndoState | Emitted when undo/redo availability changes |
| themeChange | ThemeName | Emitted when the theme changes |
| viewportChange | KritzelViewportState | Emitted on pan, zoom, or resize |
Methods
All methods are async and return Promises.
Object
addObject
Adds a new object to the canvas. The object is automatically assigned an ID, core reference, and z-index.
addObject<T extends KritzelBaseObject>(object: T): Promise<T | null>
removeObject
Removes an object from the canvas.
removeObject<T extends KritzelBaseObject>(object: T): Promise<T | null>
updateObject
Updates properties of an existing canvas object.
updateObject<T extends KritzelBaseObject>(object: T, updatedProperties: Partial<T>): Promise<T | null>
getObjectById
Retrieves a canvas object by its unique ID.
getObjectById<T extends KritzelBaseObject>(id: string): Promise<T | null>
getAllObjects
Returns all objects on the canvas across all layers.
getAllObjects<T extends KritzelBaseObject>: Promise<T[]>
findObjects
Returns all objects matching the given predicate. Excludes internal selection-related objects.
findObjects<T extends KritzelBaseObject>(predicate: (obj: KritzelBaseObject) => 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<KritzelBaseObject[]>
getCopiedObjects
Returns objects currently in the internal clipboard from a prior copy call.
getCopiedObjects: Promise<KritzelBaseObject[]>
Selection
getSelectedObjects
Returns the currently selected objects. Returns an empty array if nothing is selected.
getSelectedObjects: Promise<KritzelBaseObject[]>
selectObjects
Programmatically selects the given objects. Switches to the selection tool automatically.
selectObjects(objects: KritzelBaseObject[]): 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<KritzelViewportState>
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>
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>
centerObjectInViewport
Pans and zooms the viewport to center on the given object.
centerObjectInViewport(object: KritzelBaseObject): Promise<KritzelBaseObject>
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
createWorkspace
Creates a new workspace and emits a workspacesChange event.
createWorkspace(workspace: KritzelWorkspace): Promise<KritzelWorkspace | null>
updateWorkspace
Updates an existing workspace's metadata and emits a workspacesChange event.
updateWorkspace(workspace: KritzelWorkspace): Promise<void>
deleteWorkspace
Deletes a workspace and emits a workspacesChange event.
deleteWorkspace(workspace: KritzelWorkspace): Promise<void>
getWorkspaces
Returns all available workspaces.
getWorkspaces: Promise<KritzelWorkspace[]>
getActiveWorkspace
Returns the currently active workspace.
getActiveWorkspace: Promise<KritzelWorkspace>
Tool Management
registerTool
Registers a new drawing tool with the engine.
registerTool(
toolName: string,
toolClass: any,
toolConfig?: KritzelBrushToolConfig | KritzelLineToolConfig | KritzelTextToolConfig | KritzelShapeToolConfig
): Promise<KritzelBaseTool>
changeActiveTool
Switches the active drawing tool. Deactivates the current tool and clears any selection.
changeActiveTool(tool: KritzelBaseTool): 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>
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. If omitted, applies to the current selection.
bringForward(object?: KritzelBaseObject): Promise<void>
sendBackward
Moves an object one layer backward in the z-order. If omitted, applies to the current selection.
sendBackward(object?: KritzelBaseObject): Promise<void>
bringToFront
Moves an object to the very front of the z-order. If omitted, applies to the current selection.
bringToFront(object?: KritzelBaseObject): Promise<void>
sendToBack
Moves an object to the very back of the z-order. If omitted, applies to the current selection.
sendToBack(object?: KritzelBaseObject): Promise<void>
Alignment
alignObjects
Aligns the currently selected objects according to the specified alignment.
alignObjects(alignment: KritzelAlignment): Promise<void>
Alignment values: StartHorizontal, CenterHorizontal, EndHorizontal, StartVertical, CenterVertical, EndVertical.
Grouping
group
Groups the currently selected objects into a single group.
group: Promise<void>
ungroup
Ungroups the currently selected group back into individual objects.
ungroup: Promise<void>
Undo & Redo
undo
Undoes the last action.
undo: Promise<void>
redo
Redoes the last undone action.
redo: Promise<void>
Export
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>
Other
hideContextMenu
Hides the context menu and resets any associated selection state.
hideContextMenu: Promise<void>
getDisplayableShortcuts
Returns all registered keyboard shortcuts (without action/condition) for display in a help UI.
getDisplayableShortcuts: Promise<Omit<KritzelShortcut, 'action' | 'condition'>[]>