createDocumentEngine returns a DocumentEngine. The table below lists all DocumentEngine methods and properties. Methods that touch storage or the canvas return a promise.
Members
| Name | Type | Default | Description |
|---|---|---|---|
| canvas* | StaticCanvas | — | The canvas you passed in. |
| getDocumentInfo* | (): DocumentInfo | — | { id, createdAt, updatedAt, metadata } of the current document. |
| updateMetadata* | (changes: Record<string, unknown>): void | — | Merges changes into the metadata and marks the document as unsaved. |
| newDocument* | (options?: NewDocumentRequest): void | — | Clears the canvas and starts a new document. |
| toDocument* | (): FabricDocument | — | Serializes the canvas into a FabricDocument. Every object gets an id. |
| loadDocument* | (document: unknown, options?: LoadOptions): Promise<FabricDocument> | — | Validates, migrates and checks the assets of a document, then loads it. A failed load leaves the canvas untouched. |
| load* | (documentId: string, options?: LoadOptions): Promise<FabricDocument> | — | Loads a document from storage. It keeps documentId even if it was stored as plain Fabric JSON. |
| importFabricJson* | (json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument> | — | Opens plain Fabric JSON, such as canvas.toJSON() output, as text or as an object. |
| importSvg* | (svg: string, options?: SvgImportOptions): Promise<SvgImportResult> | — | Adds an SVG file to the canvas where its viewport puts it, as one undo step. Scripts and links to other files are removed first. |
| createVersion* | (name?: string): Promise<VersionSummary> | — | Keeps a named version of the current document. |
| listVersions* | (documentId?: string): Promise<VersionSummary[]> | — | Version summaries, newest first. |
| restoreVersion* | (versionId: string): Promise<FabricDocument> | — | Keeps an automatic Before restoring "..." version first, then loads the old content as a new, unsaved revision. |
| deleteVersion* | (versionId: string): Promise<void> | — | Deletes a version. |
| save* | (options?: SaveOptions): Promise<FabricDocument> | — | Saves through storage. Only one save runs at a time, and calls made during a save merge into one follow-up. |
| isDirty* | (): boolean | — | Whether there are unsaved changes. |
| getSaveState* | (): SaveState | — | The current SaveState. |
| registerObject* | (definition: CustomObjectDefinition): void | — | Registers a custom class after the engine was created. |
| transaction* | <Result>(label: string, work: () => Result, options?: TransactionOptions): Result | — | Records everything work changes as one labelled undo step. Nested and async work is supported. |
| setPage* | (changes: PageChanges, label?: string): void | — | Changes the page size, background, background image, overlay or canvas mask as one undo step. Marks the document unsaved. |
| commit* | (label?: string): boolean | — | Records changes your code made since the last step. Returns false if nothing changed. |
| undo* | (): Promise<boolean> | — | Undoes one step. Calls run in order. A failure rejects with HISTORY_FAILED and keeps the step. |
| redo* | (): Promise<boolean> | — | Redoes one step. Calls run in order. |
| canUndo* | (): boolean | — | Whether there is a step to undo. |
| canRedo* | (): boolean | — | Whether there is a step to redo. |
| getHistory* | (): { undo: string[]; redo: string[]; } | — | The labels of the undo and redo steps, newest first. |
| clearHistory* | (): void | — | Forgets every undo and redo step. |
| getObjectById* | (id: string): FabricObject | undefined | — | Finds any object by its id, including objects inside groups. |
| getAssetManifest* | (): AssetManifest | — | The images and fonts the current canvas uses. |
| checkAssets* | (): Promise<AssetReport> | — | Loads every image and font and reports { manifest, missingImages, unavailableFonts, warnings }. |
| replaceImage* | (oldUrl: string, newUrl: string): Promise<number> | — | Replaces every image that uses oldUrl, keeping each one's size on the page, as one undo step. Returns how many were replaced. |
| export* | (options: ExportOptions): Promise<ExportResult> | — | Exports PNG, JPEG, WebP, SVG or JSON. Rejects with EXPORT_BLOCKED and a list of problems when something would break the output. |
| preflightExport* | (options: ExportOptions): Promise<ExportPreflight> | — | Runs the export checks without exporting: { ok, problems, warnings }. |
| flushRecovery* | (): Promise<void> | — | Writes a recovery copy right now. |
| getRecoverableDocuments* | (): Promise<RecoveryRecord[]> | — | Every recovery copy, newest first. |
| getRecovery* | (documentId?: string, sessionId?: string): Promise<RecoveryRecord | undefined> | — | One recovery copy. The default is the current document. |
| restoreRecovery* | (documentId?: string, options?: RestoreRecoveryOptions): Promise<FabricDocument> | — | Loads a recovery copy as unsaved work, keeping the revision it was based on. |
| discardRecovery* | (documentId?: string, sessionId?: string): Promise<void> | — | Deletes a recovery copy. |
| getInterruptedLoad* | (): Promise<InterruptedLoad | undefined> | — | { documentId, startedAt } of a load that never finished, for example because the tab crashed. |
| on* | <Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe | — | Subscribes to an event. Returns a function that unsubscribes. |
| destroy* | (): void | — | Stops listening and cancels loads, saves and timers. Writes a recovery copy if there is unsaved work. Later calls throw ENGINE_DESTROYED. |
Method options
Load options
| Name | Type | Default | Description |
|---|---|---|---|
| restoreCanvasSize | boolean | — | Resize the canvas to the size stored in the document. |
| discardUnsavedChanges | boolean | false | Open the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES. |
| signal | AbortSignal | none | An AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED. |
| onProgress | (progress: LoadProgress) => void | none | Called with a LoadProgress as the load moves through its stages. The load:progress event carries the same values. |
Load progress
| Name | Type | Default | Description |
|---|---|---|---|
| documentId* | string | undefined | — | The id of the document being loaded, when it has one. |
| stage* | LoadStage | — | prepare, images, objects or done. |
| done* | number | — | How many images or objects are finished in this stage. |
| total* | number | — | How many there are in this stage. |
Why an image failed
| Name | Type | Default | Description |
|---|---|---|---|
| url* | string | — | The image address. |
| reason* | ImageFailureReason | — | NOT_FOUND, HTTP_ERROR, CORS, NETWORK, TIMEOUT, DECODE (not a picture the browser can read) or ABORTED. |
| message* | string | — | A sentence to show or log. |
| status | number | — | The HTTP status, when the browser lets the page read it. |
| timeoutMs | number | — | The time limit that ran out, for TIMEOUT. |
Import options
| Name | Type | Default | Description |
|---|---|---|---|
| id | string | a new id | The id of the new document. |
| metadata | Record<string, unknown> | {} | Metadata for the new document. |
| restoreCanvasSize | boolean | — | Resize the canvas to the size stored in the document.Inherited from LoadOptions. |
| discardUnsavedChanges | boolean | false | Open the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES.Inherited from LoadOptions. |
| signal | AbortSignal | none | An AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED.Inherited from LoadOptions. |
| onProgress | (progress: LoadProgress) => void | none | Called with a LoadProgress as the load moves through its stages. The load:progress event carries the same values.Inherited from LoadOptions. |
SVG import options
| Name | Type | Default | Description |
|---|---|---|---|
| viewport | "preserve" | "content" | "preserve" | preserve uses the SVG's own viewBox, width and height as the frame, so elements outside it cannot move the artwork. content uses the bounds of what is drawn. |
| offscreen | "keep" | "drop" | "clip" | "keep" | Elements entirely outside the viewport: keep, drop or clip. |
| as | "group" | "objects" | "group" | One group with a fixed layout the size of the viewport, or objects for separate objects in the same places. |
| preserveGroups | boolean | false | Rebuilds each <g> and <a> as a Fabric group with its id, opacity and clip path. Objects and groups get svgId, svgClass and svgData, which are saved. |
| left | number | 0 | Where the viewport's left edge lands on the canvas. |
| top | number | 0 | Where the viewport's top edge lands on the canvas. |
| fit | { width: number; height: number; mode?: "contain" | "cover" | "fill"; } | none | { width, height, mode? } scales the viewport into a box. mode is contain (default), cover or fill. |
| crossOrigin | "anonymous" | "use-credentials" | null | "anonymous" | Passed to images in the SVG, so the canvas can still be exported. |
| signal | AbortSignal | none | Cancels the import with LOAD_ABORTED. |
| Name | Type | Default | Description |
|---|---|---|---|
| objects* | FabricObject[] | — | The objects added to the canvas: one group, or each object. |
| viewport* | { width: number; height: number; } | — | The size of the SVG's viewport, before fit. |
| warnings* | SvgImportWarning[] | — | SVG_CONTENT_REMOVED, SVG_IMAGE_BLOCKED or SVG_OFFSCREEN_DROPPED, each with a message. |
Save options
| Name | Type | Default | Description |
|---|---|---|---|
| overwrite | boolean | false | Skip the revision check and keep this version after a SAVE_CONFLICT. |
Save state
| Name | Type | Default | Description |
|---|---|---|---|
| status* | SaveStatus | — | One of saved, unsaved, saving, error or conflict. |
| isDirty* | boolean | — | Whether there are unsaved changes. |
| isSaving* | boolean | — | Whether a save is running. |
| revision* | number | — | The revision last saved or loaded. |
| lastSavedAt* | string | undefined | — | When the last save finished, as an ISO date. |
| error* | DocumentEngineError | undefined | — | The error of the last failed save. |
Export options
| Name | Type | Default | Description |
|---|---|---|---|
| format* | ExportFormat | — | 'png', 'jpeg', 'webp', 'svg' or 'json'. |
| scale | number | 1 | Output size multiplier, such as 2 for retina screens. |
| quality | number | 0.92 | 0 to 1, for JPEG and WebP. |
| area | ExportArea | 'canvas' | 'canvas', 'content' (every object), 'selection', or { left, top, width, height }. |
| padding | number | 0 | Extra space around content or selection. |
| background | ExportBackground | 'keep' | 'keep', 'transparent' or any CSS color. |
| signal | AbortSignal | — | An AbortSignal that cancels the export. |
| svg | SvgExportOptions | {} | Options for SVG exports: curved text, and embedding images and fonts. See SvgExportOptions. |
SVG export options
| Name | Type | Default | Description |
|---|---|---|---|
| textOnPath | "vector" | "fabric" | "vector" | vector writes text on a path exactly as the canvas draws it. fabric keeps Fabric's own output, with a TEXT_ON_PATH_APPROXIMATED warning. |
| textDecorations | "shapes" | "css" | "shapes" | Underlines, overlines and line-throughs of straight text: shapes draws them where the canvas does, css keeps Fabric's text-decoration output. |
| embedImages | boolean | "require" | false | Puts every image into the file as data. true exports anyway and warns with IMAGE_NOT_EMBEDDED; "require" blocks the export with EXPORT_BLOCKED. |
| maxEmbeddedImageBytes | number | 25 MB | Larger images are not embedded. |
| embedFonts | Record<string, FontSource> | {} | Font files to embed, by family: a URL, an ArrayBuffer, a Uint8Array or a Blob. Fonts set on single letters are embedded too. |
Export result
| Name | Type | Default | Description |
|---|---|---|---|
| format* | ExportFormat | — | The format you asked for. |
| mimeType* | string | — | The MIME type of blob. |
| blob* | Blob | — | The file, ready to download or upload. |
| width* | number | — | Output width in pixels. |
| height* | number | — | Output height in pixels. |
| warnings* | AssetWarning[] | — | Asset warnings, such as a font that fell back. |
| document | FabricDocument | — | JSON exports only: the portable document. |
Page changes
setPage takes these fields. See undo and redo.
| Name | Type | Default | Description |
|---|---|---|---|
| width | number | — | Page width in pixels. |
| height | number | — | Page height in pixels. |
| background | string | TFiller | null | — | A color, gradient or pattern behind the objects. |
| backgroundImage | FabricObject | null | — | A Fabric image (or object) drawn behind the objects. |
| overlay | string | TFiller | null | — | A color, gradient or pattern drawn over the objects. |
| overlayImage | FabricObject | null | — | A Fabric image (or object) drawn over the objects. |
| clipPath | FabricObject | null | — | A shape that clips the whole canvas. |
Transaction options
| Name | Type | Default | Description |
|---|---|---|---|
| rollback | boolean | false | When work throws or rejects, puts the canvas back as it was, with no undo step and no unsaved change. The error is rethrown. |
Restore recovery options
| Name | Type | Default | Description |
|---|---|---|---|
| sessionId | string | the newest copy | Which tab's copy to restore, from RecoveryRecord.sessionId. |
| restoreCanvasSize | boolean | — | Resize the canvas to the size stored in the document.Inherited from LoadOptions. |
| discardUnsavedChanges | boolean | false | Open the document even though the current one has unsaved changes. Without it, the call refuses with UNSAVED_CHANGES.Inherited from LoadOptions. |
| signal | AbortSignal | none | An AbortSignal that cancels the load. The canvas keeps what it showed before, and the call rejects with LOAD_ABORTED.Inherited from LoadOptions. |
| onProgress | (progress: LoadProgress) => void | none | Called with a LoadProgress as the load moves through its stages. The load:progress event carries the same values.Inherited from LoadOptions. |
Rules that apply to all DocumentEngine methods
- A failed load never clears or half-fills the canvas.
- With a storage adapter,
load,loadDocument,importFabricJsonandnewDocumentrefuse withUNSAVED_CHANGESwhile there are unsaved changes, unless you passdiscardUnsavedChanges: true. - Only one save runs at a time.
savecalls made during a save merge into one follow-up. undoandredocalls run in order.exportnever changes the canvas, the history or the unsaved state.- After
destroy(), every call throwsENGINE_DESTROYED.
The guides explain each group in depth: save and load, undo and redo and export.