Embed and integrate

ExcalidrawAPI reference

Reference the imperative API for scenes, files, history, viewports, and libraries.

ExcalidrawAPI is the imperative API exposed after the editor renders. Capture it through the excalidrawAPI prop, then use it to read or update the scene, app state, files, collaborators, viewport, history, and library.

Obtain the API

tsx

const [api, setApi] = useState<ExcalidrawImperativeAPI | null>(null);

<Excalidraw excalidrawAPI={setApi} />

The callback receives the API instance. ExcalidrawAPIProvider also supplies the API context for useExcalidrawAPI() and related hooks outside the component tree.

Scene and app state

Member	Signature	Purpose
`updateScene`	`(sceneData) => void`	Update `elements`, `appState`, or `collaborators`.
`resetScene`	`(resetLoadingState?) => void`	Reset the scene; optionally clear loading state.
`getSceneElements`	`() => elements[]`	Return non-deleted elements.
`getSceneElementsIncludingDeleted`	`() => elements[]`	Return all elements, including deleted elements.
`getAppState`	`() => AppState`	Read current editor and viewport state.

tsx

api?.updateScene({
  elements: nextElements,
  appState: { viewBackgroundColor: "#f8f9fa" },
  captureUpdate: CaptureUpdateAction.IMMEDIATELY,
});

captureUpdate controls whether an update enters local undo/redo history: IMMEDIATELY, EVENTUALLY, or NEVER. Collaborator updates and unobserved app-state fields are not recorded regardless of this value.

Files and viewport

Member	Purpose
`addFiles(files)`	Add binary file data used by scene elements.
`getFiles()`	Read files currently present in the scene.
`scrollToContent(elements?)`	Center the supplied elements, or the scene when omitted.
`refresh()`	Recalculate offsets used for coordinates after layout changes.
`setActiveTool(tool)`	Set the active drawing tool.
`setCursor(cursor)` / `resetCursor()`	Set or restore the canvas cursor.

History and events

Member	Purpose
`history.clear()`	Clear the history API’s undo/redo records.
`onChange(listener)`	Subscribe to scene changes.
`onPointerDown(listener)` / `onPointerUp(listener)`	Subscribe to pointer events.
`setToast(message)`	Show a custom toast message.

Unsubscribe from event listeners when the host component unmounts. Use CaptureUpdateAction.NEVER for remote updates or scene initialization that must not become undoable.

Libraries

updateLibrary returns a promise and accepts libraryItems, merge, prompt, openLibraryMenu, and defaultStatus.

tsx

await api?.updateLibrary({
  libraryItems,
  merge: true,
  openLibraryMenu: true,
  defaultStatus: "published",
});

merge controls replacement versus merging with the current library. prompt asks for confirmation, openLibraryMenu keeps the library menu open, and defaultStatus is "unpublished" unless set to "published".

Troubleshoot common failures

Next steps

Configure the host component with component props and configuration, then apply API calls from customize embedded UI and render props.