> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/excalidraw/excalidraw/llms.txt > Use this file to discover all available pages before exploring further. # ExcalidrawProps > Complete API reference for Excalidraw component props # ExcalidrawProps Complete reference for all props accepted by the `` component. ## Event Handlers Called whenever elements, appState, or files change. ```typescript theme={null} (elements: readonly OrderedExcalidrawElement[], appState: AppState, files: BinaryFiles) => void ``` Called for incremental updates to optimize performance in collaborative scenarios. ```typescript theme={null} (event: DurableIncrement | EphemeralIncrement) => void ``` Called when pointer position or state changes. ```typescript theme={null} (payload: { pointer: { x: number; y: number; tool: "pointer" | "laser" }; button: "down" | "up"; pointersMap: Gesture["pointers"]; }) => void ``` Custom paste handler. Return `true` to prevent default paste behavior. ```typescript theme={null} (data: ClipboardData, event: ClipboardEvent | null) => Promise | boolean ``` 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. ```typescript theme={null} (nextElements: readonly ExcalidrawElement[], prevElements: readonly ExcalidrawElement[]) => ExcalidrawElement[] | void ``` Called when pointer down event occurs. ```typescript theme={null} (activeTool: AppState["activeTool"], pointerDownState: PointerDownState) => void ``` Called when pointer up event occurs. ```typescript theme={null} (activeTool: AppState["activeTool"], pointerDownState: PointerDownState) => void ``` Called when canvas scroll position or zoom changes. ```typescript theme={null} (scrollX: number, scrollY: number, zoom: Zoom) => void ``` Called when a user starts or stops following another user in collaboration mode. ```typescript theme={null} (payload: { userToFollow: { socketId: SocketId; username: string }; action: "FOLLOW" | "UNFOLLOW"; }) => void ``` Called when the library items change. ```typescript theme={null} (libraryItems: LibraryItems) => void | Promise ``` Called when a link on an element is clicked. ```typescript theme={null} (element: NonDeletedExcalidrawElement, event: CustomEvent<{ nativeEvent: MouseEvent | React.PointerEvent }>) => void ``` ## Initial State Initial data to populate the canvas. Can be a static object, a Promise, or a function returning a Promise. See [InitialData](/api/initial-data) for the complete structure. ```typescript theme={null} initialData={{ elements: [ { type: "rectangle", x: 100, y: 100, width: 200, height: 100, // ... other properties } ], appState: { viewBackgroundColor: "#ffffff", currentItemStrokeColor: "#000000", }, files: {}, }} ``` ## API Access Callback that receives the Excalidraw imperative API instance. Use this to access methods for programmatic control. ```typescript theme={null} (api: ExcalidrawImperativeAPI) => void ``` ```typescript theme={null} const [excalidrawAPI, setExcalidrawAPI] = useState(null); setExcalidrawAPI(api)} /> // Later, use the API excalidrawAPI?.updateScene({ elements: [...] }); ``` ## Collaboration Indicates whether collaboration mode is active. Enables collaboration-specific UI features. ## Custom Rendering Custom UI renderer for the top-left corner of the canvas. ```typescript theme={null} (isMobile: boolean, appState: UIAppState) => JSX.Element | null ``` Custom UI renderer for the top-right corner of the canvas. ```typescript theme={null} (isMobile: boolean, appState: UIAppState) => JSX.Element | null ``` Custom stats panel renderer. ```typescript theme={null} (elements: readonly NonDeletedExcalidrawElement[], appState: UIAppState) => JSX.Element ``` Custom renderer for embeddable elements (iframes, embeds). ```typescript theme={null} (element: NonDeleted, appState: AppState) => JSX.Element | null ``` ## Editor State When `true`, enables view-only mode. Users cannot edit the canvas. When `true`, enables zen mode which hides the UI for a distraction-free experience. When `true`, enables the grid on the canvas. When `true`, enables snapping objects to other objects and guides. The visual theme of the editor. The name of the drawing. Displayed in the UI and used as the default filename for exports. ## Localization Language code for the UI. Supports multiple languages. Examples: `"en"`, `"es"`, `"fr"`, `"de"`, `"zh-CN"`, `"ja"`, etc. ## UI Configuration Configuration object for UI features and canvas actions. See [UIOptions](/api/ui-options) for the complete reference. ```typescript theme={null} UIOptions={{ canvasActions: { changeViewBackgroundColor: false, clearCanvas: false, export: { saveFileToDisk: false }, loadScene: false, saveToActiveFile: false, toggleTheme: true, saveAsImage: true, }, tools: { image: false, }, }} ``` ## Interaction When `true`, enables automatic scroll detection when the user drags elements near the edge of the viewport. When `true`, Excalidraw keyboard shortcuts work even when the canvas is not focused. When `true`, automatically focuses the canvas on mount. When `true`, renders custom scrollbars for the canvas. ## Files & Assets Custom ID generator for uploaded files. ```typescript theme={null} (file: File) => string | Promise ``` URL to redirect to when closing the library. Used for custom library integrations. ## Links & Embeds Generates a shareable link for the selected element or group. ```typescript theme={null} (id: string, type: "element" | "group") => string ``` 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 ```typescript theme={null} // 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 When `true`, enables AI-powered features (text-to-diagram, etc.). When `true`, shows deprecated font options in the font selector. ## Children 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 ```typescript theme={null} import type { ExcalidrawProps } from "@excalidraw/excalidraw"; const MyComponent = (props: ExcalidrawProps) => { return ; }; ```