setExcalidrawAPI(api)} />
);
}
```
### Scene Methods
Update elements and/or app state.
```typescript theme={null}
updateScene: (sceneData: {
elements?: readonly ExcalidrawElement[];
appState?: Partial;
collaborators?: Map;
captureUpdate?: CaptureUpdateActionType;
}) => void;
```
Clear the canvas and reset state.
```typescript theme={null}
resetScene: (opts?: {
resetScroll?: boolean;
resetZoom?: boolean;
}) => void;
```
Get current non-deleted elements.
```typescript theme={null}
getSceneElements: () => readonly NonDeletedExcalidrawElement[];
```
Get all elements including deleted ones.
```typescript theme={null}
getSceneElementsIncludingDeleted: () => readonly ExcalidrawElement[];
```
Get elements as a Map for efficient lookup.
```typescript theme={null}
getSceneElementsMapIncludingDeleted: () => Map;
```
Apply incremental updates to elements.
```typescript theme={null}
applyDeltas: (
elementDeltas: readonly ExcalidrawElementDelta[],
options?: {
captureUpdate?: CaptureUpdateActionType;
},
) => void;
```
Mutate a single element.
```typescript theme={null}
mutateElement: (
element: ExcalidrawElement,
updates: Partial,
captureUpdate?: CaptureUpdateActionType,
) => void;
```
### State Methods
Get the current app state.
```typescript theme={null}
getAppState: () => AppState;
```
Get the scene name.
```typescript theme={null}
getName: () => string;
```
### File Methods
Get binary files (images) used in the scene.
```typescript theme={null}
getFiles: () => BinaryFiles;
```
Add binary files to the scene.
```typescript theme={null}
addFiles: (data: BinaryFileData[]) => void;
```
### Library Methods
Update library items programmatically.
```typescript theme={null}
updateLibrary: (opts: {
libraryItems: LibraryItems;
merge?: boolean;
prompt?: boolean;
openLibraryMenu?: boolean;
defaultStatus?: "published" | "unpublished";
}) => Promise;
```
### UI Methods
Change the active tool programmatically.
```typescript theme={null}
setActiveTool: (tool: {
type: ToolType | "custom";
customType?: string;
locked?: boolean;
}) => void;
```
**ToolType:** "selection" | "lasso" | "rectangle" | "diamond" | "ellipse" | "arrow" | "line" | "freedraw" | "text" | "image" | "eraser" | "hand" | "frame" | "magicframe" | "embeddable" | "laser"
Set a custom cursor.
```typescript theme={null}
setCursor: (cursor: string) => void;
```
Reset to the default cursor.
```typescript theme={null}
resetCursor: () => void;
```
Toggle a sidebar's visibility.
```typescript theme={null}
toggleSidebar: (opts: {
name: SidebarName;
tab?: SidebarTabName;
force?: boolean;
}) => boolean;
```
Show a toast notification.
```typescript theme={null}
setToast: (toast: {
message: string;
closable?: boolean;
duration?: number;
} | null) => void;
```
### Utility Methods
Force re-render of the scene.
```typescript theme={null}
refresh: () => void;
```
Scroll to view specific elements.
```typescript theme={null}
scrollToContent: (
elements?: readonly ExcalidrawElement[],
opts?: {
fitToViewport?: boolean;
animate?: boolean;
duration?: number;
},
) => void;
```
Get the editor interface details.
```typescript theme={null}
getEditorInterface: () => EditorInterface;
```
**EditorInterface:**
```typescript theme={null}
{
formFactor: "desktop" | "tablet" | "phone";
isMobile: boolean;
canFitSidebar: boolean;
}
```
Control frame rendering settings.
```typescript theme={null}
updateFrameRendering: (opts: {
enabled: boolean;
name?: boolean;
outline?: boolean;
clip?: boolean;
}) => void;
```
Use this in conjunction with `viewModeEnabled` to disable frame rendering.
Register a custom action.
```typescript theme={null}
registerAction: (action: Action) => void;
```
Clear undo/redo history.
```typescript theme={null}
history: {
clear: () => void;
};
```
Unique ID of the Excalidraw instance.
```typescript theme={null}
id: string;
```
### Event Listeners
The API also provides methods to subscribe to events. All event listener methods return an unsubscribe function.
Listen to changes. Returns unsubscribe function.
```typescript theme={null}
onChange: (
callback: (
elements: readonly ExcalidrawElement[],
appState: AppState,
files: BinaryFiles,
) => void,
) => UnsubscribeCallback;
```
Listen to increments. Returns unsubscribe function.
```typescript theme={null}
onIncrement: (
callback: (event: DurableIncrement | EphemeralIncrement) => void,
) => UnsubscribeCallback;
```
Listen to pointer down events. Returns unsubscribe function.
```typescript theme={null}
onPointerDown: (
callback: (
activeTool: AppState["activeTool"],
pointerDownState: PointerDownState,
event: React.PointerEvent,
) => void,
) => UnsubscribeCallback;
```
Listen to pointer up events. Returns unsubscribe function.
```typescript theme={null}
onPointerUp: (
callback: (
activeTool: AppState["activeTool"],
pointerDownState: PointerDownState,
event: PointerEvent,
) => void,
) => UnsubscribeCallback;
```
Listen to scroll/zoom changes. Returns unsubscribe function.
```typescript theme={null}
onScrollChange: (
callback: (scrollX: number, scrollY: number, zoom: Zoom) => void,
) => UnsubscribeCallback;
```
Listen to user follow events. Returns unsubscribe function.
```typescript theme={null}
onUserFollow: (
callback: (payload: OnUserFollowedPayload) => void,
) => UnsubscribeCallback;
```
## Complete Example
```jsx theme={null}
import { useState, useEffect } from "react";
import { Excalidraw } from "@excalidraw/excalidraw";
function App() {
const [excalidrawAPI, setExcalidrawAPI] = useState(null);
// Handle changes
const handleChange = (elements, appState, files) => {
console.log("Scene updated", { elements, appState, files });
};
// Use API after it's ready
useEffect(() => {
if (excalidrawAPI) {
// Subscribe to changes
const unsubscribe = excalidrawAPI.onChange((elements, appState, files) => {
console.log("API onChange", elements.length);
});
// Set active tool
excalidrawAPI.setActiveTool({ type: "rectangle" });
// Show toast
excalidrawAPI.setToast({
message: "Welcome to Excalidraw!",
duration: 3000,
});
return () => unsubscribe();
}
}, [excalidrawAPI]);
return (
setExcalidrawAPI(api)}
onChange={handleChange}
initialData={{
elements: [],
appState: {
viewBackgroundColor: "#ffffff",
},
}}
theme="light"
name="My Diagram"
gridModeEnabled={false}
UIOptions={{
canvasActions: {
changeViewBackgroundColor: true,
clearCanvas: true,
export: { saveFileToDisk: true },
loadScene: true,
toggleTheme: true,
},
}}
/>
);
}
export default App;
```
## Type Definitions
For complete TypeScript type definitions, see the source:
```typescript theme={null}
import type {
ExcalidrawProps,
ExcalidrawImperativeAPI,
ExcalidrawElement,
AppState,
BinaryFiles,
LibraryItems,
} from "@excalidraw/excalidraw/types";
```
## See Also
* [UI Components API](/api/ui-components) - API reference for UI components
* [Excalidraw Component](/components/excalidraw) - Usage guide and examples
* [Embedding Guide](/guides/embedding) - Learn how to embed Excalidraw
* [Customization Guide](/guides/customization) - Customize the editor appearance