API reference

Excalidraw component props and configuration

Reference the props that configure initial data, UI, callbacks, themes, and assets.

All Excalidraw props are optional. Use them to define the initial scene, observe changes, configure editor behavior, customize UI, and control asset loading.

Core props

Prop	Type	Default	Effect
`initialData`	object, `null`, or promise	`null`	Data loaded when the app starts.
`excalidrawAPI`	function	—	Receives the API after render.
`theme`	`"light"` or `"dark"`	`"light"`	Sets the editor theme.
`langCode`	string	`en`	Selects the editor language.
`name`	string	—	Names the drawing.
`viewModeEnabled`	boolean	—	Enables view mode.
`zenModeEnabled`	boolean	—	Enables zen mode.
`gridModeEnabled`	boolean	—	Enables grid mode.
`isCollaborating`	boolean	—	Marks the editor as collaborating.

Callbacks

Prop	Signature	Effect
`onChange`	`(elements, appState, files) => void`	Receives scene elements, current app state, and binary files after updates.
`onPointerUpdate`	`({ x, y }, button, pointersMap) => void`	Receives pointer coordinates, button state, and pointers.
`onPointerDown`	function	Handles pointer-down events.
`onScrollChange`	function	Handles canvas scrolling.
`onPaste`	function	Handles pasted scene content.
`onLibraryChange`	function	Receives updated library items.
`onLinkOpen`	function	Handles opened links.
`generateLinkForSelection`	function	Overrides link generation for selected elements.

tsx

<Excalidraw
  initialData={loadDraft()}
  theme="dark"
  onChange={(elements, appState, files) => saveDraft({ elements, appState, files })}
  onPointerUpdate={({ x, y }, button) => announcePointer({ x, y, button })}
/>

UIOptions

UIOptions controls supported editor actions and layout.

Field	Type	Default	Effect
`canvasActions.changeViewBackgroundColor`	boolean	`true`	Shows the background color picker.
`canvasActions.clearCanvas`	boolean	`true`	Shows Clear canvas.
`canvasActions.loadScene`	boolean	`true`	Shows Load.
`canvasActions.saveToActiveFile`	boolean	`true`	Shows Save.
`canvasActions.saveAsImage`	boolean	`true`	Shows Save as image.
`canvasActions.export`	`false` or object	object	Shows and configures export actions.
`dockedSidebarBreakpoint`	number	product default	Sets the container width at which the sidebar can dock.
`welcomeScreen`	boolean	product default	Controls the welcome screen.
`tools.image`	boolean	product default	Controls the image tool.

Export options include saveFileToDisk (default true), onExportToBackend, and renderCustomUI. Set export: false to hide the export action.

tsx

<Excalidraw
  UIOptions={{
    canvasActions: {
      changeViewBackgroundColor: false,
      clearCanvas: false,
      export: { saveFileToDisk: true },
    },
    dockedSidebarBreakpoint: 720,
  }}
/>

Children and render props

Use children for supported components such as MainMenu, Sidebar, Footer, WelcomeScreen, and LiveCollaborationTrigger. Use renderTopRightUI, renderCustomStats, and renderEmbeddable for host-provided JSX. renderEmbeddable receives the embeddable element and current appState.

Assets and layout

When self-hosting fonts, copy the package’s dist/prod/fonts directory into the public asset location and set window.EXCALIDRAW_ASSET_PATH to the same path before loading Excalidraw. The editor uses 100% of its containing block, so give the container non-zero width and height.

Custom element data

Elements can carry application data in customData, a Record<string, any> value. Supply it through initialData or update it later with updateScene or updateLibrary.

Troubleshoot common failures

Next steps

Start with Embed Excalidraw in React, then use the ExcalidrawAPI reference for runtime updates.