Export and restore utilities reference

This reference covers the public utilities for turning a scene into a canvas, blob, SVG, clipboard payload, or serialized JSON, and for normalizing imported data before you use it. It applies to embedded applications that import utilities from @excalidraw/excalidraw.

API boundary

The functions below are exported by the package. Export utilities are still being improved, so keep the package version and your integration tests aligned with the version you install. The examples use TypeScript and assume you already have an ExcalidrawElement[], an AppState, and any BinaryFiles associated with image elements.

Export a scene

exportToCanvas

Converts the supplied scene into an HTML canvas. The export options are shared with the other export functions and can include elements, app state, files, a background color, and export padding. Use the returned canvas when you need to draw additional content or call a browser canvas API.

exportToBlob

Returns a promise for a Blob generated from the canvas export.

import { exportToBlob } from "@excalidraw/excalidraw";

const blob = await exportToBlob({
  elements,
  appState,
  files,
  mimeType: "image/png",
});
const imageUrl = URL.createObjectURL(blob);
// Use imageUrl in an <img>, download link, or upload request.

exportToSvg

Returns a promise for an SVG representation of the scene. Pass elements, appState, files, and metadata; exportPadding defaults to 10.

import { exportToSvg } from "@excalidraw/excalidraw";

const svg = await exportToSvg({
  elements,
  appState,
  files,
  exportPadding: 10,
  metadata: "Architecture diagram",
});

The files value supplies image data for image elements. If you omit files, image elements cannot be exported with their associated binary data.

exportToClipboard

Exports the scene to the system clipboard as png, svg, or json.

Clipboard access is browser-controlled. Handle a rejected promise and provide a download or serialized-file alternative when permissions or browser support prevent the write.

Serialize and load data

serializeAsJSON

Serializes scene data as JSON. Use it when you need to persist or transmit elements, app state, and files in a structured form rather than rendering an image.

loadFromBlob

Loads scene data from a Blob. The package also exports loadSceneOrLibraryFromBlob and loadLibraryFromBlob when the input may contain a scene or library, or when it is specifically a library file.

restore

Combines element and app-state restoration and returns normalized data. Supply imported data, local app state, and local elements. Restoration fills missing properties with defaults.

restoreElements

Normalizes imported elements and fills missing properties. localElements lets the utility preserve an existing element's version while incrementing it and generating a new versionNonce, which is important when imported elements may already exist in the scene.

import { restoreElements, restore } from "@excalidraw/excalidraw";

const elements = restoreElements(importedElements, localElements, {
  refreshDimensions: true,
  repairBindings: true,
  normalizeIndices: true,
});

const data = restore(importedData, localAppState, localElements);

restoreLibraryItems

Normalizes imported library items. Pass the items and a default status of "published" or "unpublished".

Troubleshooting

The exported image is missing an embedded image

Cause: the export did not receive the scene's files map. Fix: pass the BinaryFiles value to exportToCanvas, exportToBlob, or exportToSvg, then verify that the image appears in the output.

Restored text has stale dimensions

Cause: refreshDimensions defaults to false. Fix: set refreshDimensions: true for the restore operation, then verify the text layout before updating the scene.

Imported arrows or text are disconnected

Cause: imported bindings refer to elements that are missing or changed. Fix: restore with repairBindings: true, then inspect the resulting bindings before publishing the scene.

Clipboard export is rejected

Cause: the browser denied clipboard access or does not support the required API. Fix: catch the rejection and offer exportToBlob, exportToSvg, or serializeAsJSON as a download or upload path.

Next step

For the data that these utilities consume and produce, see Excalidraw file and clipboard format. For programmatic scene construction, see Element data and creation reference.