Editor

The <KritzelEditor> is the high-level, full-featured whiteboard component. It wraps <KritzelEngine> 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

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
toolbarItems	KritzelToolbarItem[]	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
isToolbarVisible	boolean	true	Show/hide the toolbar
isUtilityPanelVisible	boolean	true	Show/hide the utility panel (undo/redo, zoom)
syncConfig	KritzelSyncConfig	undefined	Sync provider configuration
workspaces	KritzelWorkspace[]	undefined	Optional authoritative workspace catalog for this editor instance. Provider-only workspaces are hidden but not deleted.

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

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

Property	Type	Description
cursorTarget	HTMLElement	Element used as cursor target. Defaults to the editor container if omitted.
customSvgIcons	KritzelSvgIconMap	Custom SVG icon definitions.
globalContextMenuItems	ContextMenuItem[]	Context menu items shown on the canvas background.
isMoreMenuVisible	boolean	Controls visibility of the More menu.
isToolbarVisible	boolean	Controls toolbar visibility.
isUtilityPanelVisible	boolean	Controls utility panel visibility.
isWorkspaceManagerVisible	boolean	Controls workspace manager visibility.
isZoomPanelVisible	boolean	Controls zoom panel visibility.
moreMenuItems	IKritzelMenuItem[]	Custom entries for the More dropdown menu.
objectContextMenuItems	ContextMenuItem[]	Context menu items shown for selected objects.

Events

No UI-specific events.

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<KritzelShortcut, "action" | "condition">[]>.

triggerNotification

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

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>

addObjects

Adds multiple objects in one undo step and render cycle.

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

removeObject

Removes an object from the canvas.

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

removeObjects

Removes multiple objects in one batch operation.

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

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[]>

---

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>

panToObject

Pans to an object without changing scale.

panToObject(object: KritzelBaseObject): 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: KritzelBaseObject): Promise<KritzelBaseObject>

centerObjects

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

centerObjects(objects: KritzelBaseObject[]): 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 a KritzelWorkspace instance.

createWorkspace(workspace: KritzelWorkspace): Promise<KritzelWorkspace | 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: 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>

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?: KritzelBrushToolConfig | KritzelLineToolConfig | KritzelTextToolConfig | KritzelShapeToolConfig
): Promise<KritzelBaseTool>

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. 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 & 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: KritzelExportFormat): Promise<boolean>

exportSelectedObject

Exports the selected object in the requested format.

exportSelectedObject(format: KritzelExportFormat): Promise<void>

getSelectedObjectSupportedExportFormats

Returns export formats supported by the selected object.

getSelectedObjectSupportedExportFormats(): Promise<KritzelExportFormat[]>

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

Property	Type	Description
customFonts	KritzelFontMap	Registers fonts for runtime rendering and text-tool usage.
theme	ThemeCode	Current active theme.
themes	KritzelTheme[]	Available theme definitions.

Events

Event	Payload Type	Description
themeChange	ThemeCode	Emitted when the active theme changes.

Methods

registerFonts

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

registerFonts(fonts: KritzelFontMap): Promise<void>

Localization

Props

Property	Type	Description
fallbackLocale	LocaleCode	Locale used to resolve terms missing from the active locale.
locale	LocaleCode	Current locale code used by the editor.
locales	KritzelLocale[]	Available locale definitions with optional term overrides.

Events

Event	Payload Type	Description
localeChange	LocaleCode	Emitted when the active locale changes.

Methods

registerLocales

Registers locale definitions: registerLocales(locales: KritzelLocale[]): 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: KritzelTermKey, vars?: KritzelTermVars): Promise<string>.

User Management

Props

Property	Type	Description
user	IKritzelUser	Current authenticated user for awareness and collaboration state.
loginConfig	KritzelLoginConfig	Login dialog provider configuration.

Events

Event	Payload Type	Description
login	LoginEvent	Emitted when login is triggered from the authentication dialog.
logout	void	Emitted 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

Property	Type	Description
activeUsers	IKritzelUser[]	Other users currently in the session.
syncConfig	KritzelSyncConfig	Real-time collaboration provider configuration.

Events

Event	Payload Type	Description
awarenessChange	AwarenessStateMap	Emitted when collaborative awareness state changes.

Methods

reinitSync

Reinitializes the active synchronization provider connection.

reinitSync(): Promise<void>