The main entry exports a few document engine helpers next to createDocumentEngine. The browser helpers wire the engine into the page. The document helpers work in Node without a canvas.
Browser helpers
function bindKeyboardShortcuts(engine: UndoRedoTarget, options?: KeyboardShortcutOptions): () => voidCtrl/Cmd+Z undoes. Ctrl/Cmd+Shift+Z and Ctrl+Y redo. Ignored while the user types in an input or in Fabric text. Returns an unbind function.
function bindUnsavedChangesWarning(engine: UnsavedChangesSource, target?: EventTarget): () => voidAsks the browser to confirm before a page with unsaved changes closes. Returns an unbind function.
function downloadExport(result: DownloadableExport, fileName?: string): voidStarts a browser download of an export result.
| Name | Type | Default | Description |
|---|---|---|---|
| target | EventTarget | window | Where to listen for key presses. |
Clipboard and layers
function createClipboard(engine: DocumentEngine, options?: ClipboardOptions): ClipboardA clipboard for one engine. Copies keep custom properties and the real position of objects in groups and selections. Each paste gets fresh ids and is one undo step.
| Name | Type | Default | Description |
|---|---|---|---|
| copy* | (objects?: readonly FabricObject[]): number | — | Copies objects, or the selection. Returns how many were copied. |
| cut* | (objects?: readonly FabricObject[]): number | — | Copies, then removes the objects as one undo step. The next paste lands in place. |
| paste* | (options?: PasteOptions): Promise<FabricObject[]> | — | Adds a copy with fresh ids as one undo step, and selects it. Returns the new objects. |
| hasContent* | (): boolean | — | Whether something was copied. |
| read* | (): ClipboardContent | undefined | — | The copied objects as plain JSON, for the system clipboard. |
| write* | (content: unknown): void | — | Replaces the content, for example with JSON from another tab. It is checked like a loaded document. |
| clear* | (): void | — | Empties the clipboard. |
| Name | Type | Default | Description |
|---|---|---|---|
| offset | number | 10 | How far each paste moves from the last one. |
| limits | ContentLimits | none | Limits for content passed to write, as for loading documents. |
| Name | Type | Default | Description |
|---|---|---|---|
| target | DocumentEngine | the clipboard's engine | The engine to paste into. |
| offset | number | the clipboard's offset | Overrides the offset for this paste. |
| select | boolean | true | Selects the pasted objects on an interactive canvas. |
function bringToFront(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): booleanMoves objects, or the selection, to the top of the stack as one undo step. Returns false when nothing moved.
function sendToBack(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): booleanMoves objects, or the selection, to the bottom of the stack as one undo step.
function bringForward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): booleanMoves objects one step up. Selected neighbours move as a block.
function sendBackward(engine: DocumentEngine, objects?: readonly FabricObject[], options?: LayerOptions): booleanMoves objects one step down. Selected neighbours move as a block.
function moveToIndex(engine: DocumentEngine, objects: readonly FabricObject[], index: number, options?: LayerOptions): booleanMoves objects to an index counted from the bottom, as a block.
function getLayers(engine: DocumentEngine): LayerInfo[]The top-level objects from top to bottom, for a layers panel.
| Name | Type | Default | Description |
|---|---|---|---|
| pinned | LayerPin | none | Objects this returns true for never move and keep their place, such as a background or a frame. |
How they work together is shown in copy, paste and layers.
Rendering many documents
function renderDocuments(documents: Iterable<unknown> | AsyncIterable<unknown>, options: RenderDocumentsOptions): AsyncGenerator<RenderedDocument, void, undefined>Renders many documents on a few reused off-screen canvases and yields each result as it finishes. Every canvas it creates is freed.
| Name | Type | Default | Description |
|---|---|---|---|
| concurrency | number | 2 | How many documents render at the same time. |
| signal | AbortSignal | none | Stops the batch with EXPORT_ABORTED. |
| onProgress | (progress: { done: number; total: number | undefined; }) => void | none | Called with { done, total } after each document. |
| customObjects | CustomObjectDefinition[] | [] | Custom classes, as for createDocumentEngine. |
| assets | AssetOptions | {} | Asset options, as for createDocumentEngine. |
| limits | ContentLimits | defaults | Safety limits, as for createDocumentEngine. |
| Name | Type | Default | Description |
|---|---|---|---|
| index* | number | — | Position of the document in the input. |
| documentId* | string | undefined | — | The document's id, when it has one. |
| result | ExportResult | — | The export result, when it rendered. |
| error | DocumentEngineError | — | Why it failed. The other documents still render. |
State for any framework
function createDocumentStateStore(engine: DocumentEngine): DocumentStateStoreFramework-free { getSnapshot, subscribe, destroy } with DocumentState. Fits Vue, Svelte and useSyncExternalStore.
Document helpers
These document engine helpers run anywhere, including a server:
function validateDocument(value: unknown): DocumentIssue[]Checks a value against the document format. Returns a list of issues with the path of each problem.
function migrateDocument(value: unknown, context: MigrationContext, steps?: Readonly<Record<number, Migration>>, targetVersion?: number): MigrationResultUpgrades an older document or plain Fabric JSON to the current format. Useful for server-side batch upgrades.
function detectSchemaVersion(value: unknown): number | undefinedReturns 1 for a document, 0 for plain Fabric JSON, otherwise undefined.
function secureDocument(input: unknown, limits?: ContentLimits): unknownRemoves prototype keys and enforces the object and depth limits. Throws UNSAFE_DOCUMENT.
function isSafeImageUrl(url: string): booleanThe default image address rule: http, https, blob, relative addresses and data:image/ are allowed.
Errors
function isDocumentEngineError(value: unknown): value is DocumentEngineErrorType guard for DocumentEngineError, which carries a stable code.
Example: check an upload on the server
import {
migrateDocument,
secureDocument,
validateDocument,
} from "fabricjs-document-engine";
const safe = secureDocument(body, { maxObjects: 20000 });
const { document } = migrateDocument(safe, {
canvasWidth: 1200,
canvasHeight: 800,
});
const issues = validateDocument(document);More on these document engine helpers is in security and migration.