` component takes these props children (all are optional):\n\n| name | type | description |\n| --- | --- | --- |\n| className | string |\n| children | React.ReactNode
| Content you want to render inside the sidebar header, sibling of the header buttons. |\n\nFor example code, see the example [`App.tsx`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/example/App.tsx#L524) file.\n\n#### `viewModeEnabled`\n\nThis 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.\n\n#### `zenModeEnabled`\n\nThis 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.\n\n#### `gridModeEnabled`\n\nThis 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.\n\n#### `libraryReturnUrl`\n\nIf supplied, this URL will be used when user tries to install a library from [libraries.excalidraw.com](https://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.\n\n#### `theme`\n\nThis 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](#onChange) callback).\n\nYou can use [`THEME`](#THEME-1) to specify the theme.\n\n#### `name`\n\nThis 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.\n\n#### `UIOptions`\n\nThis prop can be used to customise UI of Excalidraw. Currently we support customising [`canvasActions`](#canvasActions) and [`dockedSidebarBreakpoint`](dockedSidebarBreakpoint). It accepts the below parameters\n\n\n{ canvasActions: CanvasActions }\n\n\n##### canvasActions\n\n| Attribute | Type | Default | Description |\n| --- | --- | --- | --- |\n| `changeViewBackgroundColor` | boolean | true | Implies whether to show `Background color picker` |\n| `clearCanvas` | boolean | true | Implies whether to show `Clear canvas button` |\n| `export` | false | [exportOpts](#exportOpts) | { saveFileToDisk: true } | This prop allows to customize the UI inside the export dialog. By default it shows the \"saveFileToDisk\". If this prop is `false` the export button will not be rendered. For more details visit [`exportOpts`](#exportOpts). |\n| `loadScene` | boolean | true | Implies whether to show `Load button` |\n| `saveToActiveFile` | boolean | true | Implies whether to show `Save button` to save to current file |\n| `toggleTheme` | boolean | null | null | Implies whether to show `Theme toggle`. When defined as `boolean`, takes precedence over [`props.theme`](#theme) to show `Theme toggle` |\n| `saveAsImage` | boolean | true | Implies whether to show `Save as image button` |\n\n##### `dockedSidebarBreakpoint`\n\nThis prop indicates at what point should we break to a docked, permanent sidebar. If not passed it defaults to [`MQ_RIGHT_SIDEBAR_MAX_WIDTH_PORTRAIT`](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L167). If the `width` of the `excalidraw` container exceeds `dockedSidebarBreakpoint`, the sidebar will be dockable. If user choses to dock the sidebar, it will push the right part of the UI towards the left, making space for the sidebar as shown below.\n\n\n\n#### `exportOpts`\n\nThe below attributes can be set in `UIOptions.canvasActions.export` to customize the export dialog. If `UIOptions.canvasActions.export` is `false` the export button will not be rendered.\n\n| Attribute | Type | Default | Description |\n| --- | --- | --- | --- |\n| `saveFileToDisk` | boolean | true | Implies if save file to disk button should be shown |\n| `onExportToBackend` | (exportedElements: readonly NonDeletedExcalidrawElement[],appState: AppState,canvas: HTMLCanvasElement | null) => void
| | This callback is triggered when the shareable-link button is clicked in the export dialog. The link button will only be shown if this callback is passed. |\n| `renderCustomUI` | (exportedElements: readonly NonDeletedExcalidrawElement[],appState: AppState,canvas: HTMLCanvasElement | null) => void
| | This callback should be supplied if you want to render custom UI in the export dialog. |\n\n#### `onPaste`\n\nThis 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.\n\n\n(data: ClipboardData, event: ClipboardEvent | null) => boolean\n
\n\nThis callback must return a `boolean` value or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to a boolean value.\n\nIn 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).\n\n#### `importLibrary`\n\nImports library from given URL. You should call this on `hashchange`, passing the `addLibrary` value if you detect it as shown below. Optionally pass a CSRF `token` to skip prompting during installation (retrievable via `token` key from the url coming from [https://libraries.excalidraw.com](https://libraries.excalidraw.com/)).\n\n```js\nuseEffect(() => {\n const onHashChange = () => {\n const hash = new URLSearchParams(window.location.hash.slice(1));\n const libraryUrl = hash.get(\"addLibrary\");\n if (libraryUrl) {\n excalidrawRef.current.importLibrary(libraryUrl, hash.get(\"token\"));\n }\n };\n window.addEventListener(\"hashchange\", onHashChange, false);\n return () => {\n window.removeEventListener(\"hashchange\", onHashChange);\n };\n}, []);\n```\n\nTry out the [Demo](#Demo) to see it in action.\n\n#### `setToast`\n\nThis API can be used to show the toast with custom message.\n\n\n({ message: string,\n closable?:boolean,\n duration?:number } | null) => void\n\n\n| Attribute | type | Description |\n| --- | --- | --- |\n| message | string | The message to be shown on the toast. |\n| closable | boolean | Indicates whether to show the closable button on toast to dismiss the toast. |\n| duration | number | Determines the duration after which the toast should auto dismiss. To prevent autodimiss you can pass `Infinity`. |\n\nTo dismiss an existing toast you can simple pass `null`\n\n```js\nsetToast(null);\n```\n\n#### `setActiveTool`\n\nThis API has the below signature. It sets the `tool` passed in param as the active tool.\n\n\n(tool: { type: typeof SHAPES[number][\"value\"] | \"eraser\" } | { type: \"custom\"; customType: string }) => void\n\n\n#### `setCursor`\n\nThis API can be used to customise the mouse cursor on the canvas and has the below signature. It sets the mouse cursor to the cursor passed in param.\n\n\n(cursor: string) => void\n
\n\n#### `toggleMenu`\n\n\n(type: \"library\" | \"customSidebar\", force?: boolean) => boolean\n
\n\nThis API can be used to toggle a specific menu (currently only the sidebars), and returns whether the menu was toggled on or off. If the `force` flag passed, it will force the menu to be toggled either on/off based on the boolean passed.\n\nThis API is especially useful when you render a custom sidebar using [`renderSidebar`](#renderSidebar) prop, and you want to toggle it from your app based on a user action.\n\n#### `resetCursor`\n\nThis API can be used to reset to default mouse cursor.\n\n#### `detectScroll`\n\nIndicates 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()`](#ref) method).\n\n#### `handleKeyboardGlobally`\n\nIndicates 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.\n\nEnable 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).\n\n#### `onLibraryChange`\n\nThis callback if supplied will get triggered when the library is updated and has the below signature.\n\n\n(items: LibraryItems) => void | Promise\n
\n\nIt 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.\n\n#### `id`\n\nThe unique id of the excalidraw component. This can be used to identify the excalidraw component, for example importing the library items to the excalidraw component from where it was initiated when you have multiple excalidraw components rendered on the same page as shown in [multiple excalidraw demo](https://codesandbox.io/s/multiple-excalidraw-k1xx5).\n\n#### `autoFocus`\n\nThis prop implies whether to focus the Excalidraw component on page load. Defaults to false.\n\n#### `generateIdForFile`\n\nAllows you to override `id` generation for files added on canvas (images). By default, an SHA-1 digest of the file is used.\n\n```\n(file: File) => string | Promise\n```\n\n#### `onLinkOpen`\n\nThis 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()`.\n\n```\n(element: ExcalidrawElement, event: CustomEvent<{ nativeEvent: MouseEvent }>) => void\n```\n\nExample:\n\n```ts\nconst history = useHistory();\n\n// open internal links using the app's router, but opens external links in\n// a new tab/window\nconst onLinkOpen: ExcalidrawProps[\"onLinkOpen\"] = useCallback(\n (element, event) => {\n const link = element.link;\n const { nativeEvent } = event.detail;\n const isNewTab = nativeEvent.ctrlKey || nativeEvent.metaKey;\n const isNewWindow = nativeEvent.shiftKey;\n const isInternalLink =\n link.startsWith(\"/\") || link.includes(window.location.origin);\n if (isInternalLink && !isNewTab && !isNewWindow) {\n history.push(link.replace(window.location.origin, \"\"));\n // signal that we're handling the redirect ourselves\n event.preventDefault();\n }\n },\n [history],\n);\n```\n\n#### `onPointerDown`\n\nThis prop if passed will be triggered on pointer down events and has the below signature.\n\n\n(activeTool: AppState[\"activeTool\"], pointerDownState: PointerDownState) => void\n
\n\n#### `onScrollChange`\n\nThis prop if passed will be triggered when canvas is scrolled and has the below signature.\n\n```ts\n(scrollX: number, scrollY: number) => void\n```\n\n### Restore utilities\n\n#### `restoreAppState`\n\n**_Signature_**\n\n\nrestoreAppState(appState: ImportedDataState[\"appState\"], localAppState: Partial<AppState> | null): AppState\n
\n\n**_How to use_**\n\n```js\nimport { restoreAppState } from \"@excalidraw/excalidraw\";\n```\n\nThis function will make sure all the keys have appropriate values in [appState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) and if any key is missing, it will be set to default value.\n\nWhen `localAppState` is supplied, it's used in place of values that are missing (`undefined`) in `appState` instead of defaults. Use this as a way to not override user's defaults if you persist them. Required: supply `null`/`undefined` if not applicable.\n\n#### `restoreElements`\n\n**_Signature_**\n\n\nrestoreElements(\n elements: ImportedDataState[\"elements\"],\n localElements: ExcalidrawElement[] | null | undefined): ExcalidrawElement[],\n refreshDimensions: boolean\n)\n
\n\n**_How to use_**\n\n```js\nimport { restoreElements } from \"@excalidraw/excalidraw\";\n```\n\nThis function will make sure all properties of element is correctly set and if any attribute is missing, it will be set to default value.\n\nWhen `localElements` are supplied, they are used to ensure that existing restored elements reuse `version` (and increment it), and regenerate `versionNonce`. Use this when you import elements which may already be present in the scene to ensure that you do not disregard the newly imported elements if you're using element version to detect the updates.\n\nParameter `refreshDimensions` indicates whether we should also recalculate text element dimensions. Defaults to `false`. Since this is a potentially costly operation, you may want to disable it if you restore elements in tight loops, such as during collaboration.\n\n#### `restore`\n\n**_Signature_**\n\n\nrestoreElements(\n data: ImportedDataState,\n localAppState: Partial<AppState> | null | undefined,\n localElements: ExcalidrawElement[] | null | undefined): DataState\n)\n
\n\nSee [`restoreAppState()`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#restoreAppState) about `localAppState`, and [`restoreElements()`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#restoreElements) about `localElements`.\n\n**_How to use_**\n\n```js\nimport { restore } from \"@excalidraw/excalidraw\";\n```\n\nThis function makes sure elements and state is set to appropriate values and set to default value if not present. It is a combination of [restoreElements](#restoreElements) and [restoreAppState](#restoreAppState).\n\n#### `restoreLibraryItems`\n\n**_Signature_**\n\n\nrestoreLibraryItems(libraryItems: ImportedDataState[\"libraryItems\"], defaultStatus: \"published\" | \"unpublished\")\n
\n\n**_How to use_**\n\n```js\nimport { restoreLibraryItems } from \"@excalidraw/excalidraw\";\n\nrestoreLibraryItems(libraryItems, \"unpublished\");\n```\n\nThis function normalizes library items elements, adding missing values when needed.\n\n### Export utilities\n\n#### `exportToCanvas`\n\n**_Signature_**\n\nexportToCanvas({\n elements,\n appState\n getDimensions,\n files,\n exportPadding?: number;\n}: ExportOpts\n\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types) | | The elements to be exported to canvas |\n| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L12) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |\n| getDimensions | `(width: number, height: number) => { width: number, height: number, scale?: number }` | undefined | A function which returns the `width`, `height`, and optionally `scale` (defaults `1`), with which canvas is to be exported. |\n| maxWidthOrHeight | `number` | undefined | The maximum width or height of the exported image. If provided, `getDimensions` is ignored. |\n| files | [BinaryFiles](The [`BinaryFiles`](<[BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64)>) | undefined | The files added to the scene. |\n| exportPadding | number | 10 | The padding to be added on canvas |\n\n**How to use**\n\n```js\nimport { exportToCanvas } from \"@excalidraw/excalidraw\";\n```\n\nThis function returns the canvas with the exported elements, appState and dimensions.\n\n#### `exportToBlob`\n\n**_Signature_**\n\n\nexportToBlob(\n opts: ExportOpts & {\n mimeType?: string,\n quality?: number,\n exportPadding?: number;\n})\n\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| opts | | | This param is passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exportToCanvas) |\n| mimeType | string | \"image/png\" | Indicates the image format |\n| quality | number | 0.92 | A value between 0 and 1 indicating the [image quality](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob#parameters). Applies only to `image/jpeg`/`image/webp` MIME types. |\n| exportPadding | number | 10 | The padding to be added on canvas |\n\n**How to use**\n\n```js\nimport { exportToBlob } from \"@excalidraw/excalidraw\";\n```\n\nReturns a promise which resolves with a [blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob). It internally uses [canvas.ToBlob](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob).\n\n#### `exportToSvg`\n\n**_Signature_**\n\n\nexportToSvg({\n elements: ExcalidrawElement[],\n appState: AppState,\n exportPadding?: number,\n metadata?: string,\n files?: BinaryFiles\n})\n\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L106) | | The elements to exported as svg |\n| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |\n| exportPadding | number | 10 | The padding to be added on canvas |\n| files | [BinaryFiles](The [`BinaryFiles`](<[BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64)>) | undefined | The files added to the scene. |\n\nThis function returns a promise which resolves to svg of the exported drawing.\n\n#### `exportToClipboard`\n\n**_Signature_**\n\n\nexportToClipboard(\n opts: ExportOpts & {\n mimeType?: string,\n quality?: number;\n type: 'png' | 'svg' |'json'\n})\n\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- | --- | --- |\n| opts | | | This param is same as the params passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exportToCanvas). |\n| mimeType | string | \"image/png\" | Indicates the image format, this will be used when exporting as `png`. |\n| quality | number | 0.92 | A value between 0 and 1 indicating the [image quality](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob#parameters). Applies only to `image/jpeg`/`image/webp` MIME types. This will be used when exporting as `png`. |\n| type | 'png' | 'svg' | 'json' | | This determines the format to which the scene data should be exported. |\n\n**How to use**\n\n```js\nimport { exportToClipboard } from \"@excalidraw/excalidraw\";\n```\n\nCopies the scene data in the specified format (determined by `type`) to clipboard.\n\n##### Additional attributes of appState for `export\\*` APIs\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| exportBackground | boolean | true | Indicates whether background should be exported |\n| viewBackgroundColor | string | #fff | The default background color |\n| exportWithDarkMode | boolean | false | Indicates whether to export with dark mode |\n| exportEmbedScene | boolean | false | Indicates whether scene data should be embedded in svg/png. This will increase the image size. |\n\n### Extra API's\n\n#### `serializeAsJSON`\n\n**_Signature_**\n\n\nserializeAsJSON({\n elements: ExcalidrawElement[],\n appState: AppState,\n}): string\n\n\nTakes the scene elements and state and returns a JSON string. Deleted `elements`as well as most properties from `AppState` are removed from the resulting JSON. (see [`serializeAsJSON()`](https://github.com/excalidraw/excalidraw/blob/master/src/data/json.ts#L16) source for details).\n\nIf you want to overwrite the source field in the JSON string, you can set `window.EXCALIDRAW_EXPORT_SOURCE` to the desired value.\n\n#### `serializeLibr","readmeFilename":"README.md"}