ExcalidrawProps

Complete API reference for Excalidraw component props

ExcalidrawProps

Complete reference for all props accepted by the <Excalidraw /> component.

Event Handlers

onChange · function

Called whenever elements, appState, or files change.

(elements: readonly OrderedExcalidrawElement[], 
 appState: AppState, 
 files: BinaryFiles) => void

onIncrement · function

Called for incremental updates to optimize performance in collaborative scenarios.

(event: DurableIncrement | EphemeralIncrement) => void

onPointerUpdate · function

Called when pointer position or state changes.

(payload: {
  pointer: { x: number; y: number; tool: "pointer" | "laser" };
  button: "down" | "up";
  pointersMap: Gesture["pointers"];
}) => void

onPaste · function

Custom paste handler. Return true to prevent default paste behavior.

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

onDuplicate · function

Called when elements are duplicated (via mouse-drag, keyboard, paste, library insert, etc.).

Return modified elements to override the default duplication behavior. You should return all elements including deleted ones, and avoid mutating the original elements.

(nextElements: readonly ExcalidrawElement[],
 prevElements: readonly ExcalidrawElement[]) => ExcalidrawElement[] | void

onPointerDown · function

Called when pointer down event occurs.

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

onPointerUp · function

Called when pointer up event occurs.

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

onScrollChange · function

Called when canvas scroll position or zoom changes.

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

onUserFollow · function

Called when a user starts or stops following another user in collaboration mode.

(payload: {
  userToFollow: { socketId: SocketId; username: string };
  action: "FOLLOW" | "UNFOLLOW";
}) => void

onLibraryChange · function

Called when the library items change.

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

onLinkOpen · function

Called when a link on an element is clicked.

(element: NonDeletedExcalidrawElement,
 event: CustomEvent<{
   nativeEvent: MouseEvent | React.PointerEvent<HTMLCanvasElement>
 }>) => void

Initial State

initialData · ExcalidrawInitialDataState | (() => Promise<ExcalidrawInitialDataState | null>) | null

Initial data to populate the canvas. Can be a static object, a Promise, or a function returning a Promise.

See InitialData for the complete structure.

Show Example

initialData={{
  elements: [
    {
      type: "rectangle",
      x: 100,
      y: 100,
      width: 200,
      height: 100,
      // ... other properties
    }
  ],
  appState: {
    viewBackgroundColor: "#ffffff",
    currentItemStrokeColor: "#000000",
  },
  files: {},
}}

API Access

excalidrawAPI · function

Callback that receives the Excalidraw imperative API instance. Use this to access methods for programmatic control.

(api: ExcalidrawImperativeAPI) => void

Show Example

const [excalidrawAPI, setExcalidrawAPI] = useState(null);

<Excalidraw excalidrawAPI={(api) => setExcalidrawAPI(api)} />

// Later, use the API
excalidrawAPI?.updateScene({ elements: [...] });

Collaboration

isCollaborating · boolean · default: "false"

Indicates whether collaboration mode is active. Enables collaboration-specific UI features.

Custom Rendering

renderTopLeftUI · function

Custom UI renderer for the top-left corner of the canvas.

(isMobile: boolean, appState: UIAppState) => JSX.Element | null

renderTopRightUI · function

Custom UI renderer for the top-right corner of the canvas.

(isMobile: boolean, appState: UIAppState) => JSX.Element | null

renderCustomStats · function

Custom stats panel renderer.

(elements: readonly NonDeletedExcalidrawElement[],
 appState: UIAppState) => JSX.Element

renderEmbeddable · function

Custom renderer for embeddable elements (iframes, embeds).

(element: NonDeleted<ExcalidrawEmbeddableElement>,
 appState: AppState) => JSX.Element | null

Editor State

viewModeEnabled · boolean · default: "false"

When true, enables view-only mode. Users cannot edit the canvas.

zenModeEnabled · boolean · default: "false"

When true, enables zen mode which hides the UI for a distraction-free experience.

gridModeEnabled · boolean · default: "false"

When true, enables the grid on the canvas.

objectsSnapModeEnabled · boolean · default: "false"

When true, enables snapping objects to other objects and guides.

theme · 'light' | 'dark' · default: "'light'"

The visual theme of the editor.

name · string

The name of the drawing. Displayed in the UI and used as the default filename for exports.

Localization

langCode · string

Language code for the UI. Supports multiple languages.

Examples: "en", "es", "fr", "de", "zh-CN", "ja", etc.

UI Configuration

UIOptions · Partial<UIOptions>

Configuration object for UI features and canvas actions.

See UIOptions for the complete reference.

Show Example

UIOptions={{
  canvasActions: {
    changeViewBackgroundColor: false,
    clearCanvas: false,
    export: { saveFileToDisk: false },
    loadScene: false,
    saveToActiveFile: false,
    toggleTheme: true,
    saveAsImage: true,
  },
  tools: {
    image: false,
  },
}}

Interaction

detectScroll · boolean · default: "true"

When true, enables automatic scroll detection when the user drags elements near the edge of the viewport.

handleKeyboardGlobally · boolean · default: "false"

When true, Excalidraw keyboard shortcuts work even when the canvas is not focused.

autoFocus · boolean · default: "false"

When true, automatically focuses the canvas on mount.

renderScrollbars · boolean · default: "true"

When true, renders custom scrollbars for the canvas.

Files & Assets

generateIdForFile · function

Custom ID generator for uploaded files.

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

libraryReturnUrl · string

URL to redirect to when closing the library. Used for custom library integrations.

Links & Embeds

generateLinkForSelection · function

Generates a shareable link for the selected element or group.

(id: string, type: "element" | "group") => string

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

Validates whether a URL can be embedded in the canvas.

• boolean: Enable/disable all embeds
• string[]: Whitelist of allowed domains
• RegExp | RegExp[]: Pattern(s) to match allowed URLs
• function: Custom validation function

Show Examples

// Disable all embeds
validateEmbeddable={false}

// Whitelist specific domains
validateEmbeddable={["youtube.com", "vimeo.com"]}

// Use regex pattern
validateEmbeddable={/^https:\/\/(www\.)?youtube\.com/}

// Custom validator
validateEmbeddable={(link) => {
  return link.startsWith("https://");
}}

Features

aiEnabled · boolean · default: "true"

When true, enables AI-powered features (text-to-diagram, etc.).

showDeprecatedFonts · boolean · default: "false"

When true, shows deprecated font options in the font selector.

Children

children · React.ReactNode

Custom React components to render inside the Excalidraw container.

Useful for adding custom overlays, modals, or other UI elements that need to be rendered within the Excalidraw context.

Type Definitions

import type { ExcalidrawProps } from "@excalidraw/excalidraw";

const MyComponent = (props: ExcalidrawProps) => {
  return <Excalidraw {...props} />;
};