|
|
@@ -1,34 +1,34 @@
|
|
|
# Props
|
|
|
|
|
|
-All `props` are *optional*.
|
|
|
+All `props` are _optional_.
|
|
|
|
|
|
| Name | Type | Default | Description |
|
|
|
-| --- | --- | --- | --- |
|
|
|
-| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` | `null` | <code>Promise<object | null></code> | `null` | The initial data with which app loads. |
|
|
|
-| [`ref`](/docs/@excalidraw/excalidraw/api/props/ref) | `object` | _ | `Ref` to be passed to Excalidraw |
|
|
|
-| [`isCollaborating`](#iscollaborating) | `boolean` | _ | This indicates if the app is in `collaboration` mode |
|
|
|
-| [`onChange`](#onchange) | `function` | _ | This callback is triggered whenever the component updates due to any change. This callback will receive the excalidraw `elements` and the current `app state`. |
|
|
|
-| [`onPointerUpdate`](#onpointerupdate) | `function` | _ | Callback triggered when mouse pointer is updated. |
|
|
|
-| [`onPointerDown`](#onpointerdown) | `function` | _ | This prop if passed gets triggered on pointer down evenets |
|
|
|
-| [`onScrollChange`](#onscrollchange) | `function` | _ | This prop if passed gets triggered when scrolling the canvas. |
|
|
|
-| [`onPaste`](#onpaste) | `function` | _ | Callback to be triggered if passed when the something is pasted in to the scene |
|
|
|
-| [`onLibraryChange`](#onlibrarychange) | `function` | _ | The callback if supplied is triggered when the library is updated and receives the library items. |
|
|
|
-| [`onLinkOpen`](#onlinkopen) | `function` | _ | The callback if supplied is triggered when any link is opened. |
|
|
|
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
|
+| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` | `null` | <code>Promise<object | null></code> | `null` | The initial data with which app loads. |
|
|
|
+| [`ref`](/docs/@excalidraw/excalidraw/api/props/ref) | `object` | \_ | `Ref` to be passed to Excalidraw |
|
|
|
+| [`isCollaborating`](#iscollaborating) | `boolean` | \_ | This indicates if the app is in `collaboration` mode |
|
|
|
+| [`onChange`](#onchange) | `function` | \_ | This callback is triggered whenever the component updates due to any change. This callback will receive the excalidraw `elements` and the current `app state`. |
|
|
|
+| [`onPointerUpdate`](#onpointerupdate) | `function` | \_ | Callback triggered when mouse pointer is updated. |
|
|
|
+| [`onPointerDown`](#onpointerdown) | `function` | \_ | This prop if passed gets triggered on pointer down evenets |
|
|
|
+| [`onScrollChange`](#onscrollchange) | `function` | \_ | This prop if passed gets triggered when scrolling the canvas. |
|
|
|
+| [`onPaste`](#onpaste) | `function` | \_ | Callback to be triggered if passed when the something is pasted in to the scene |
|
|
|
+| [`onLibraryChange`](#onlibrarychange) | `function` | \_ | The callback if supplied is triggered when the library is updated and receives the library items. |
|
|
|
+| [`onLinkOpen`](#onlinkopen) | `function` | \_ | The callback if supplied is triggered when any link is opened. |
|
|
|
| [`langCode`](#langcode) | `string` | `en` | Language code string to be used in Excalidraw |
|
|
|
-| [`renderTopRightUI`](/docs/@excalidraw/excalidraw/api/props/render-props#rendertoprightui) | `function` | _ | Render function that renders custom UI in top right corner |
|
|
|
-| [`renderCustomStats`](/docs/@excalidraw/excalidraw/api/props/render-props#rendercustomstats) | `function` | _ | Render function that can be used to render custom stats on the stats dialog. |
|
|
|
-| [`renderSidebar`](/docs/@excalidraw/excalidraw/api/props/render-props#rendersidebar) | `function` | _ | Render function that renders custom sidebar. |
|
|
|
-| [`viewModeEnabled`](#viewmodeenabled) | `boolean` | _ | This indicates if the app is in `view` mode. |
|
|
|
-| [`zenModeEnabled`](#zenmodeenabled) | `boolean` | _ | This indicates if the `zen` mode is enabled |
|
|
|
-| [`gridModeEnabled`](#gridmodeenabled) | `boolean` | _ | This indicates if the `grid` mode is enabled |
|
|
|
-| [`libraryReturnUrl`](#libraryreturnurl) | `string` | _ | What URL should [libraries.excalidraw.com](https://libraries.excalidraw.com) be installed to |
|
|
|
+| [`renderTopRightUI`](/docs/@excalidraw/excalidraw/api/props/render-props#rendertoprightui) | `function` | \_ | Render function that renders custom UI in top right corner |
|
|
|
+| [`renderCustomStats`](/docs/@excalidraw/excalidraw/api/props/render-props#rendercustomstats) | `function` | \_ | Render function that can be used to render custom stats on the stats dialog. |
|
|
|
+| [`renderSidebar`](/docs/@excalidraw/excalidraw/api/props/render-props#rendersidebar) | `function` | \_ | Render function that renders custom sidebar. |
|
|
|
+| [`viewModeEnabled`](#viewmodeenabled) | `boolean` | \_ | This indicates if the app is in `view` mode. |
|
|
|
+| [`zenModeEnabled`](#zenmodeenabled) | `boolean` | \_ | This indicates if the `zen` mode is enabled |
|
|
|
+| [`gridModeEnabled`](#gridmodeenabled) | `boolean` | \_ | This indicates if the `grid` mode is enabled |
|
|
|
+| [`libraryReturnUrl`](#libraryreturnurl) | `string` | \_ | What URL should [libraries.excalidraw.com](https://libraries.excalidraw.com) be installed to |
|
|
|
| [`theme`](#theme) | `"light"` | `"dark"` | `"light"` | The theme of the Excalidraw component |
|
|
|
| [`name`](#name) | `string` | | Name of the drawing |
|
|
|
| [`UIOptions`](/docs/@excalidraw/excalidraw/api/props/ui-options) | `object` | [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L151) | To customise UI options. Currently we support customising [`canvas actions`](#canvasactions) |
|
|
|
| [`detectScroll`](#detectscroll) | `boolean` | `true` | Indicates whether to update the offsets when nearest ancestor is scrolled. |
|
|
|
| [`handleKeyboardGlobally`](#handlekeyboardglobally) | `boolean` | `false` | Indicates whether to bind the keyboard events to document. |
|
|
|
| [`autoFocus`](#autofocus) | `boolean` | `false` | indicates whether to focus the Excalidraw component on page load |
|
|
|
-| [`generateIdForFile`](#generateidforfile) | `function` | _ | Allows you to override `id` generation for files added on canvas |
|
|
|
+| [`generateIdForFile`](#generateidforfile) | `function` | \_ | Allows you to override `id` generation for files added on canvas |
|
|
|
| [`validateEmbeddable`](#validateEmbeddable) | string[] | `boolean | RegExp | RegExp[] | ((link: string) => boolean | undefined)` | \_ | use for custom src url validation |
|
|
|
| [`renderEmbeddable`](/docs/@excalidraw/excalidraw/api/props/render-props#renderEmbeddable) | `function` | \_ | Render function that can override the built-in `<iframe>` |
|
|
|
|
|
|
@@ -95,7 +95,14 @@ This callback is triggered when mouse pointer is updated.
|
|
|
This prop if passed will be triggered on pointer down events and has the below signature.
|
|
|
|
|
|
<pre>
|
|
|
-(activeTool: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115"> AppState["activeTool"]</a>, pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">PointerDownState</a>) => void
|
|
|
+ (activeTool:{" "}
|
|
|
+ <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115">
|
|
|
+ {" "}
|
|
|
+ AppState["activeTool"]
|
|
|
+ </a>
|
|
|
+ , pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">
|
|
|
+ PointerDownState
|
|
|
+ </a>) => void
|
|
|
</pre>
|
|
|
|
|
|
### onScrollChange
|
|
|
@@ -111,7 +118,11 @@ This prop if passed will be triggered when canvas is scrolled and has the below
|
|
|
This 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.
|
|
|
|
|
|
<pre>
|
|
|
-(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">ClipboardData</a>, event: ClipboardEvent | null) => boolean
|
|
|
+ (data:{" "}
|
|
|
+ <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">
|
|
|
+ ClipboardData
|
|
|
+ </a>
|
|
|
+ , event: ClipboardEvent | null) => boolean
|
|
|
</pre>
|
|
|
|
|
|
This 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.
|
|
|
@@ -137,8 +148,11 @@ It is invoked with empty items when user clears the library. You can use this ca
|
|
|
This 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()`.
|
|
|
|
|
|
<pre>
|
|
|
-(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">ExcalidrawElement</a>,
|
|
|
- event: CustomEvent<{ nativeEvent: MouseEvent }>) => void
|
|
|
+ (element:{" "}
|
|
|
+ <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
|
|
|
+ ExcalidrawElement
|
|
|
+ </a>
|
|
|
+ , event: CustomEvent<{ nativeEvent: MouseEvent }>) => void
|
|
|
</pre>
|
|
|
|
|
|
Example:
|
|
|
@@ -181,31 +195,30 @@ import { defaultLang, languages } from "@excalidraw/excalidraw";
|
|
|
|
|
|
### viewModeEnabled
|
|
|
|
|
|
-This 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.
|
|
|
+This 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.
|
|
|
|
|
|
### zenModeEnabled
|
|
|
|
|
|
-This 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.
|
|
|
+This 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.
|
|
|
|
|
|
### gridModeEnabled
|
|
|
|
|
|
-This 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.
|
|
|
+This 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.
|
|
|
|
|
|
### libraryReturnUrl
|
|
|
|
|
|
If 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.
|
|
|
+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.
|
|
|
|
|
|
### theme
|
|
|
|
|
|
-This 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).
|
|
|
+This 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).
|
|
|
|
|
|
You can use [`THEME`](/docs/@excalidraw/excalidraw/api/utils#theme) to specify the theme.
|
|
|
|
|
|
### name
|
|
|
|
|
|
-This 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.
|
|
|
-
|
|
|
+This 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.
|
|
|
|
|
|
### detectScroll
|
|
|
|
|
|
@@ -226,7 +239,7 @@ This prop indicates whether to `focus` the Excalidraw component on page load. De
|
|
|
Allows you to override `id` generation for files added on canvas (images). By default, an SHA-1 digest of the file is used.
|
|
|
|
|
|
```tsx
|
|
|
-(file: File) => string | Promise<string>
|
|
|
+(file: File) => string | Promise<string>;
|
|
|
```
|
|
|
|
|
|
### validateEmbeddable
|
|
|
@@ -237,4 +250,4 @@ validateEmbeddable?: boolean | string[] | RegExp | RegExp[] | ((link: string) =>
|
|
|
|
|
|
This is an optional property. By default we support a handful of well-known sites. You may allow additional sites or disallow the default ones by supplying a custom validator. If you pass `true`, all URLs will be allowed. You can also supply a list of hostnames, RegExp (or list of RegExp objects), or a function. If the function returns `undefined`, the built-in validator will be used.
|
|
|
|
|
|
-Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.
|
|
|
+Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.
|
dwelle