# API reference


**Site index:** [https://excalidraw.2plot.dev/llms.txt](https://excalidraw.2plot.dev/llms.txt) — every page on this site, as Markdown.  
**Network index:** [https://2plot.dev/llms.txt](https://2plot.dev/llms.txt) — The 2plot network; start here to discover sibling sites.  
**Sibling sites:** 13 more in The 2plot network — listed in the site index above.  
**Sitemap:** https://excalidraw.2plot.dev/sitemap.xml  

## dash_excalidraw

### DashExcalidraw

DashExcalidraw is an Excalidraw drawing canvas bound to Dash via a
JSON-safe prop surface. See the per-prop docs above for the full
catalog; see the README for the command/event round-trip pattern used
for imperative actions like exports.

| prop | type | default | description |
|---|---|---|---|
| `id` | string |  | Unique ID to identify this component in Dash callbacks. |
| `UIOptions` | dict |  | Subset of Excalidraw `UIOptions` that is JSON-serializable. Use this to toggle individual canvas actions, show/hide the welcome screen, etc. |
| `appState` | objectOf |  | Full serializable app state (view background, zoom, scroll, grid mode, zen mode, theme, active tool, …). Read-only from Python. |
| `autoFocus` | bool |  | Focus the canvas on mount. @,default,true |
| `command` | dict |  | Write to this prop from a Python callback to dispatch an imperative action into Excalidraw. Shape:  ```python {"id": "unique-string", "type": "updateScene", "payload": {...}} ```  Supported `type` values:  - `updateScene` / `resetScene` / `addFiles`  - `scrollToContent` / `setActiveTool` / `setToast` / `toggleSidebar`  - `updateLibrary`  - `exportToSvg` / `exportToBlob` / `exportToCanvas`  Each dispatch is de-duplicated by `id`, and the component clears the prop (sets it to `None`) once the action completes so React re-renders do not re-fire. |
| `detectScroll` | bool |  | Whether Excalidraw listens to wheel-scroll events on the canvas. @,default,true |
| `elements` | list of objectOf |  | Current Excalidraw element array. Written via setProps on every scene change — read-only from Python callbacks. |
| `externalizedSerializedData` | string |  | Same envelope as `serializedData`, but every `files[*].dataURL` that still holds an inline `data:` URI is replaced with `null`. External URLs (those dispatched via the `replaceFiles` command) are retained as-is. Persist this variant to avoid paying the base64 cost; inline bytes can be rehydrated later via `dash_excalidraw.helpers.restore_inline_files`. |
| `files` | objectOf |  | Map of binary file entries (image id -> {dataURL, mimeType, ...}). Read-only from Python. |
| `gridModeEnabled` | bool |  | Snap to grid and draw the grid background. @,default,false |
| `handleKeyboardGlobally` | bool |  | When true, keyboard shortcuts work even when the canvas is not focused. Turn off if your Dash app has other inputs that might conflict. @,default,true |
| `height` | string |  | CSS height of the canvas container. Excalidraw fills its parent, so this is the number to change when the canvas looks too short. @,default,"600px" |
| `hideExcalidrawLinks` | bool |  | When `true` (default), injects CSS that hides Excalidraw's built-in "Excalidraw links" menu group (GitHub / Discord / Twitter). Set to `false` if you actually want those links visible to users. |
| `initialData` | dict |  | Initial scene contents passed to Excalidraw on mount. Shape: `{elements, appState, files, libraryItems, scrollToContent}`. Updating this prop after mount has no effect — use `command` with `type="updateScene"` to change the scene imperatively. |
| `interceptLinkOpens` | bool |  | When `true`, the wrapper calls `event.preventDefault()` on every `lastLinkOpen` event so Python can handle the click itself (typically by opening a `dmc.Drawer`). Default `false` — links open in a new tab normally. |
| `isCollaborating` | bool |  | Renders the "currently-editing" collaborator UI. You'll also need to feed `appState.collaborators`; the wrapper does not bundle a transport layer. @,default,false |
| `langCode` | string |  | UI language code (e.g. `en`, `fr-FR`, `zh-CN`). @,default,"en" |
| `lastExport` | objectOf |  | Result of the most recent export command: `{timestamp, id, type, result, error?}`. Match `id` against the command you dispatched to correlate responses. |
| `lastExternalDrop` | objectOf |  | Fires when the wrapper's drop handler intercepts a drop that Excalidraw itself doesn't accept (non-image files, or any multi- file drop). Payload:    {     timestamp,     files: [{name, mimeType, dataURL, size}, ...],     dropPoint: {x, y},                  # scene coords     placeholderIds: [elemId, ...],      # one id per non-image file,                                         # pointing at the rectangle we                                         # placed on the canvas so you                                         # can update its `link` after                                         # upload.   } |
| `lastFileAdded` | objectOf |  | Fires when one or more new file ids appear in `files` with an inline `data:` dataURL. Payload:    {     timestamp,     fileId, mimeType, dataURL, size,   # first new file (back-compat)     files: [       {fileId, mimeType, dataURL, size},       ...                              # every new file in this change     ],   }  Single-file callbacks can keep reading `event['fileId']`; batch callbacks iterate `event['files']`. `size` is decoded byte count. |
| `lastLibraryChange` | objectOf |  | Snapshot of the last library change `{timestamp, items}`. |
| `lastLinkOpen` | objectOf |  | Snapshot of the last link-open event `{timestamp, elementId, url}` — fired when a user Cmd/Ctrl-clicks an element with a hyperlink. |
| `lastPaste` | objectOf |  | Snapshot of the last clipboard paste `{timestamp, data}`. The wrapper cannot cancel the paste from Python; if you need to intercept, clean up in a follow-up callback that modifies scene state afterward. |
| `lastPointerDown` | objectOf |  | Snapshot of the last pointer-down event: `{timestamp, activeTool, pointer: {x, y}}`. |
| `lastPointerMove` | objectOf |  | Throttled pointer-move snapshot `{timestamp, pointer, button, pointersMap}`. Throttled by `pointerMoveThrottleMs` (default 50 ms). |
| `lastPointerUp` | objectOf |  | Snapshot of the last pointer-up event: `{timestamp, activeTool, pointer: {x, y}}`. |
| `lastScrollChange` | objectOf |  | Throttled scroll/zoom snapshot `{timestamp, scrollX, scrollY}`. |
| `libraryReturnUrl` | string |  | Optional URL appended to the "Browse Library" button in the sidebar. When unset Excalidraw uses its own default. |
| `name` | string |  | Drawing name — appears in the top bar and in serialized export filenames. |
| `pointerMoveThrottleMs` | number |  | Debounce interval for `lastPointerMove` writes (milliseconds). @,default,50 |
| `sceneVersion` | number |  | Monotonic scene version from `excalidrawAPI.getSceneVersion()`. Useful for change detection without diffing element arrays. |
| `scrollThrottleMs` | number |  | Debounce interval for `lastScrollChange` writes (milliseconds). @,default,100 |
| `serializedData` | string |  | JSON string of the canonical Excalidraw serialized envelope `{type, version, source, elements, appState, files}`. Suitable to pass to `dash.dcc.Store` and later restore via `initialData`. |
| `theme` | one of 'light', 'dark' |  | Canvas color theme. @,default,"light" |
| `validateEmbeddable` | bool \| list of string |  | Controls which URLs may be embedded inside Excalidraw frames. Pass `true` to allow all, `false` to deny all, or a list of domain-glob strings (e.g. `["*.youtube.com", "excalidraw.com"]`) which the wrapper compiles to case-insensitive RegExps. |
| `viewModeEnabled` | bool |  | View-only mode: disables drawing tools; pan/zoom still available. @,default,false |
| `width` | string |  | CSS width of the canvas container. @,default,"100%" |
| `zenModeEnabled` | bool |  | Zen mode hides most of the chrome for a distraction-free canvas. @,default,false |