Props

All props are optional.

Name	Type	Default	Description
initialData	object | null | Promise<object | null>	null	The initial data with which app loads.
excalidrawAPI	function	_	Callback triggered with the excalidraw api once rendered
isCollaborating	boolean	_	This indicates if the app is in collaboration mode
onChange	function	_	This callback is triggered whenever the component updates due to any change. This callback will receive the excalidraw elements and the current app state.
onPointerUpdate	function	_	Callback triggered when mouse pointer is updated.
onPointerDown	function	_	This prop if passed gets triggered on pointer down evenets
onScrollChange	function	_	This prop if passed gets triggered when scrolling the canvas.
onPaste	function	_	Callback to be triggered if passed when the something is pasted in to the scene
onLibraryChange	function	_	The callback if supplied is triggered when the library is updated and receives the library items.
onLinkOpen	function	_	The callback if supplied is triggered when any link is opened.
langCode	string	en	Language code string to be used in Excalidraw
renderTopRightUI	function	_	Render function that renders custom UI in top right corner
renderCustomStats	function	_	Render function that can be used to render custom stats on the stats dialog.
viewModeEnabled	boolean	_	This indicates if the app is in view mode.
zenModeEnabled	boolean	_	This indicates if the zen mode is enabled
gridModeEnabled	boolean	_	This indicates if the grid mode is enabled
libraryReturnUrl	string	_	What URL should libraries.excalidraw.com be installed to
theme	"light" | "dark"	"light"	The theme of the Excalidraw component
name	string		Name of the drawing
UIOptions	object	DEFAULT UI OPTIONS	To customise UI options. Currently we support customising canvas actions
detectScroll	boolean	true	Indicates whether to update the offsets when nearest ancestor is scrolled.
handleKeyboardGlobally	boolean	false	Indicates whether to bind the keyboard events to document.
autoFocus	boolean	false	indicates whether to focus the Excalidraw component on page load
generateIdForFile	function	_	Allows you to override id generation for files added on canvas
validateEmbeddable	string[]	`boolean	RegExp
renderEmbeddable	function	_	Render function that can override the built-in <iframe>

Storing custom data on Excalidraw elements

Beyond attributes that Excalidraw elements already support, you can store custom data on each element in a customData object. The type of the attribute is Record<string, any> and is optional.

You can use this to add any extra information you need to keep track of.

You can add customData to elements when passing them as initialData, or using updateScene / updateLibrary afterwards.

{
  type: "rectangle",
  id: "oDVXy8D6rom3H1-LLH2-f",
  customData: {customId: '162'},
}

isCollaborating

This prop indicates if the app is in collaboration mode.

onChange

Every time component updates, this callback if passed will get triggered and has the below signature.

(excalidrawElements, appState, files) => void;

1. excalidrawElements: Array of excalidrawElements in the scene.

2. appState: AppState of the scene.

3. files: The BinaryFiles which are added to the scene.

Here you can try saving the data to your backend or local storage for example.

onPointerUpdate

This callback is triggered when mouse pointer is updated.

({ x, y }, button, pointersMap}) => void;

1.{x, y}: Pointer coordinates

2.button: The position of the button. This will be one of ["down", "up"]

3.pointersMap: pointers map of the scene

(exportedElements, appState, canvas) => void

1. exportedElements: An array of non deleted elements which needs to be exported.
2. appState: AppState of the scene.
3. canvas: The HTMLCanvasElement of the scene.

onPointerDown

This prop if passed will be triggered on pointer down events and has the below signature.

(activeTool:  AppState["activeTool"], pointerDownState: PointerDownState) => void

onScrollChange

This prop if passed will be triggered when canvas is scrolled and has the below signature.

(scrollX: number, scrollY: number) => void

onPaste

This callback is triggered if passed when something is pasted into the scene. You can use this callback in case you want to do something additional when the paste event occurs.

(data: ClipboardData, event: ClipboardEvent | null) => boolean

This callback must return a boolean value or a promise which resolves to a boolean value.

In case you want to prevent the excalidraw paste action you must return false, it will stop the native excalidraw clipboard management flow (nothing will be pasted into the scene).

onLibraryChange

This callback if supplied will get triggered when the library is updated and has the below signature.

(items: LibraryItems) => void | Promise<any>

It is invoked with empty items when user clears the library. You can use this callback when you want to do something additional when library is updated for example persisting it to local storage.

onLinkOpen

This prop if passed will be triggered when clicked on link. To handle the redirect yourself (such as when using your own router for internal links), you must call event.preventDefault().

(element: ExcalidrawElement, event: CustomEvent<{ nativeEvent: MouseEvent }>) => void

Example:

const history = useHistory();

// open internal links using the app's router, but opens external links in
// a new tab/window
const onLinkOpen: ExcalidrawProps["onLinkOpen"] = useCallback(
  (element, event) => {
    const link = element.link;
    const { nativeEvent } = event.detail;
    const isNewTab = nativeEvent.ctrlKey || nativeEvent.metaKey;
    const isNewWindow = nativeEvent.shiftKey;
    const isInternalLink =
      link.startsWith("/") || link.includes(window.location.origin);
    if (isInternalLink && !isNewTab && !isNewWindow) {
      history.push(link.replace(window.location.origin, ""));
      // signal that we're handling the redirect ourselves
      event.preventDefault();
    }
  },
  [history],
);

langCode

Determines the language of the UI. It should be one of the available language codes. Defaults to en (English). We also export default language and supported languages which you can import as shown below.

import { defaultLang, languages } from "@excalidraw/excalidraw";

name	type
defaultLang	string
languages	Language[]

viewModeEnabled

This prop indicates whether the app is in view mode. When supplied, the value takes precedence over intialData.appState.viewModeEnabled, the view mode will be fully controlled by the host app, and users won't be able to toggle it from within the app.

zenModeEnabled

This prop indicates whether the app is in zen mode. When supplied, the value takes precedence over intialData.appState.zenModeEnabled, the zen mode will be fully controlled by the host app, and users won't be able to toggle it from within the app.

gridModeEnabled

This prop indicates whether the shows the grid. When supplied, the value takes precedence over intialData.appState.gridModeEnabled, the grid will be fully controlled by the host app, and users won't be able to toggle it from within the app.

libraryReturnUrl

If supplied, this URL will be used when user tries to install a library from libraries.excalidraw.com.
Defaults to window.location.origin + window.location.pathname. To install the libraries in the same tab from which it was opened, you need to set window.name (to any alphanumeric string) — if it's not set it will open in a new tab.

theme

This prop controls Excalidraw's theme. When supplied, the value takes precedence over intialData.appState.theme, the theme will be fully controlled by the host app, and users won't be able to toggle it from within the app unless UIOptions.canvasActions.toggleTheme is set to true, in which case the theme prop will control Excalidraw's default theme with ability to allow theme switching (you must take care of updating the theme prop when you detect a change to appState.theme from the onChange callback).

You can use THEME to specify the theme.

name

This prop sets the name of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over intialData.appState.name, the name will be fully controlled by host app and the users won't be able to edit from within Excalidraw.

detectScroll

Indicates whether Excalidraw should listen for scroll event on the nearest scrollable container in the DOM tree and recompute the coordinates (e.g. to correctly handle the cursor) when the component's position changes. You can disable this when you either know this doesn't affect your app or you want to take care of it yourself (calling the refresh() method).

handleKeyboardGlobally

Indicates whether to bind keyboard events to document. Disabled by default, meaning the keyboard events are bound to the Excalidraw component. This allows for multiple Excalidraw components to live on the same page, and ensures that Excalidraw keyboard handling doesn't collide with your app's (or the browser) when the component isn't focused.

Enable this if you want Excalidraw to handle keyboard even if the component isn't focused (e.g. a user is interacting with the navbar, sidebar, or similar).

autoFocus

This prop indicates whether to focus the Excalidraw component on page load. Defaults to false.

generateIdForFile

Allows you to override id generation for files added on canvas (images). By default, an SHA-1 digest of the file is used.

(file: File) => string | Promise<string>

validateEmbeddable

validateEmbeddable?: boolean | string[] | RegExp | RegExp[] | ((link: string) => boolean | undefined)

This is an optional property. By default we support a handful of well-known sites. You may allow additional sites or disallow the default ones by supplying a custom validator. If you pass true, all URLs will be allowed. You can also supply a list of hostnames, RegExp (or list of RegExp objects), or a function. If the function returns undefined, the built-in validator will be used.

Supplying a list of hostnames (with or without www.) is the preferred way to allow a specific list of domains.