setExcalidrawAPI(api)}} />;
+}
+```
+
+You can use this prop when you want to access some [Excalidraw APIs](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L616). We expose the below APIs :point_down:
| API | Signature | Usage |
| --- | --- | --- |
-| ready | `boolean` | This is set to true once Excalidraw is rendered |
-| [readyPromise](#readypromise) | `function` | This promise will be resolved with the api once excalidraw has rendered. This will be helpful when you want do some action on the host app once this promise resolves. For this to work you will have to pass ref as shown [here](#readypromise) |
| [updateScene](#updatescene) | `function` | updates the scene with the sceneData |
-| [updateLibrary](#updatelibrary) | `function` | updates the scene with the sceneData |
+| [updateLibrary](#updatelibrary) | `function` | updates the library |
| [addFiles](#addfiles) | `function` | add files data to the appState |
| [resetScene](#resetscene) | `function` | Resets the scene. If `resetLoadingState` is passed as true then it will also force set the loading state to false. |
| [getSceneElementsIncludingDeleted](#getsceneelementsincludingdeleted) | `function` | Returns all the elements including the deleted in the scene |
@@ -25,61 +37,22 @@ You can pass a `ref` when you want to access some excalidraw APIs. We expose the
| [setActiveTool](#setactivetool) | `function` | This API can be used to set the active tool |
| [setCursor](#setcursor) | `function` | This API can be used to set customise the mouse cursor on the canvas |
| [resetCursor](#resetcursor) | `function` | This API can be used to reset to default mouse cursor on the canvas |
-| [toggleMenu](#togglemenu) | `function` | Toggles specific menus on/off |
+| [toggleSidebar](#toggleSidebar) | `function` | Toggles specific sidebar on/off |
+| [onChange](#onChange) | `function` | Subscribes to change events |
+| [onPointerDown](#onPointerDown) | `function` | Subscribes to `pointerdown` events |
+| [onPointerUp](#onPointerUp) | `function` | Subscribes to `pointerup` events |
-## readyPromise
+:::info The `Ref` support has been removed in v0.17.0 so if you are using refs, please update the integration to use the `excalidrawAPI`.
-
- const excalidrawRef = { current:{ readyPromise:
-
- resolvablePromise
-
- } }
-
+Additionally `ready` and `readyPromise` from the API have been discontinued. These APIs were found to be superfluous, and as part of the effort to streamline the APIs and maintain simplicity, they were removed in version v0.17.0.
-Since plain object is passed as a `ref`, the `readyPromise` is resolved as soon as the component is mounted. Most of the time you will not need this unless you have a specific use case where you can't pass the `ref` in the react way and want to do some action on the host when this promise resolves.
-
-```jsx showLineNumbers
-const resolvablePromise = () => {
- let resolve;
- let reject;
- const promise = new Promise((_resolve, _reject) => {
- resolve = _resolve;
- reject = _reject;
- });
- promise.resolve = resolve;
- promise.reject = reject;
- return promise;
-};
-
-const App = () => {
- const excalidrawRef = useMemo(
- () => ({
- current: {
- readyPromise: resolvablePromise(),
- },
- }),
- [],
- );
-
- useEffect(() => {
- excalidrawRef.current.readyPromise.then((api) => {
- console.log("loaded", api);
- });
- }, [excalidrawRef]);
- return (
-
-
-
- );
-};
-```
+:::
## updateScene
(scene:{" "}
-
+
sceneData
) => void
@@ -89,10 +62,10 @@ You can use this function to update the scene with the sceneData. It accepts the
| Name | Type | Description |
| --- | --- | --- |
-| `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L38) | The `elements` to be updated in the scene |
-| `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L39) | The `appState` to be updated in the scene. |
-| `collaborators` | MapCollaborator> | The list of collaborators to be updated in the scene. |
-| `commitToHistory` | `boolean` | Implies if the `history (undo/redo)` should be recorded. Defaults to `false`. |
+| `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L38) | The `elements` to be updated in the scene |
+| `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L39) | The `appState` to be updated in the scene. |
+| `collaborators` | MapCollaborator> | The list of collaborators to be updated in the scene. |
+| `commitToStore` | `boolean` | Implies if the change should be captured and commited to the `store`. Commited changes are emmitted and listened to by other components, such as `History` for undo / redo purposes. Defaults to `false`. |
```jsx live
function App() {
@@ -139,8 +112,10 @@ function App() {
return (
Click to update the scene
-
-
setExcalidrawAPI(api)} />
+
+ setExcalidrawAPI(api)} />
);
}
@@ -150,13 +125,13 @@ function App() {
(opts: {
libraryItems:{" "}
-
+
LibraryItemsSource
;
merge?: boolean;
prompt?: boolean;
openLibraryMenu?: boolean;
defaultStatus?: "unpublished" | "published";
}) => Promise<
-
+
LibraryItems
>
@@ -166,7 +141,7 @@ You can use this function to update the library. It accepts the below attributes
| Name | Type | Default | Description |
| --- | --- | --- | --- |
-| `libraryItems` | [LibraryItemsSource](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L249) | \_ | The `libraryItems` to be replaced/merged with current library |
+| `libraryItems` | [LibraryItemsSource](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L249) | \_ | The `libraryItems` to be replaced/merged with current library |
| `merge` | boolean | `false` | Whether to merge with existing library items. |
| `prompt` | boolean | `false` | Whether to prompt user for confirmation. |
| `openLibraryMenu` | boolean | `false` | Keep the library menu open after library is updated. |
@@ -187,7 +162,8 @@ function App() {
return (
Click to update the library items
-
setExcalidrawAPI(api)}
- // initial data retrieved from https://github.com/excalidraw/excalidraw/blob/master/dev-docs/src/initialData.js
+ excalidrawAPI={(api) => setExcalidrawAPI(api)}
+ // initial data retrieved from https://github.com/excalidraw/excalidraw/blob/master/dev-docs/packages/excalidraw/initialData.js
initialData={{
libraryItems: initialData.libraryItems,
appState: { openSidebar: "library" },
@@ -230,7 +204,7 @@ function App() {
(files:{" "}
-
+
BinaryFileData
) => void
@@ -250,7 +224,7 @@ Resets the scene. If `resetLoadingState` is passed as true then it will also for
() =>{" "}
-
+
ExcalidrawElement[]
@@ -261,7 +235,7 @@ Returns all the elements including the deleted in the scene.
() => NonDeleted<
-
+
ExcalidrawElement
[]>
@@ -273,7 +247,7 @@ Returns all the elements excluding the deleted in the scene
() =>{" "}
-
+
AppState
@@ -292,19 +266,34 @@ This is the history API. history.clear() will clear the history.
## scrollToContent
-
- (target?:{" "}
-
- ExcalidrawElement
- {" "}
- |{" "}
-
- ExcalidrawElement
-
- []) => void
-
+```tsx
+(
+ target?: ExcalidrawElement | ExcalidrawElement[],
+ opts?:
+ | {
+ fitToContent?: boolean;
+ animate?: boolean;
+ duration?: number;
+ }
+ | {
+ fitToViewport?: boolean;
+ viewportZoomFactor?: number;
+ animate?: boolean;
+ duration?: number;
+ }
+) => void
+```
-Scroll the nearest element out of the elements supplied to the center. Defaults to the elements on the scene.
+Scroll the nearest element out of the elements supplied to the center of the viewport. Defaults to the elements on the scene.
+
+| Attribute | type | default | Description |
+| --- | --- | --- | --- |
+| target | [ExcalidrawElement](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L115) | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L115) | All scene elements | The element(s) to scroll to. |
+| opts.fitToContent | boolean | false | Whether to fit the elements to viewport by automatically changing zoom as needed. Note that the zoom range is between 10%-100%. |
+| opts.fitToViewport | boolean | false | Similar to fitToContent but the zoom range is not limited. If elements are smaller than the viewport, zoom will go above 100%. |
+| opts.viewportZoomFactor | number | 0.7 | when fitToViewport=true, how much screen should the content cover, between 0.1 (10%) and 1 (100%) |
+| opts.animate | boolean | false | Whether to animate between starting and ending position. Note that for larger scenes the animation may not be smooth due to performance issues. |
+| opts.duration | number | 500 | Duration of the animation if `opts.animate` is `true`. |
## refresh
@@ -323,7 +312,7 @@ For any other cases if the position of excalidraw is updated (example due to scr
This API can be used to show the toast with custom message.
```tsx
-({ message: string, closable?:boolean,duration?:number
+({ message: string, closable?:boolean,duration?:number
} | null) => void
```
@@ -347,7 +336,7 @@ The unique id of the excalidraw component. This can be used to identify the exca
() =>{" "}
-
+
files
@@ -358,29 +347,43 @@ This API can be used to get the files present in the scene. It may contain files
This API has the below signature. It sets the `tool` passed in param as the active tool.
+```ts
+(
+ tool: (
+ | (
+ | { type: Exclude }
+ | {
+ type: Extract;
+ insertOnCanvasDirectly?: boolean;
+ }
+ )
+ | { type: "custom"; customType: string }
+ ) & { locked?: boolean },
+) => {};
+```
-
-(tool:
{ type: SHAPES[number]["value"]| "eraser" } |
{ type: "custom"; customType: string }) => void
-
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | [ToolType](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L91) | `selection` | The tool type which should be set as active tool. When setting `image` as active tool, the insertion onto canvas when using image tool is disabled by default, so you can enable it by setting `insertOnCanvasDirectly` to `true` |
+| `locked` | `boolean` | `false` | Indicates whether the the active tool should be locked. It behaves the same way when using the `lock` tool in the editor interface |
## setCursor
-This 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.
+This 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.
```tsx
(cursor: string) => void
```
-## toggleMenu
+## toggleSidebar
```tsx
-(type: "library" | "customSidebar", force?: boolean) => boolean;
+(opts: { name: string; tab?: string; force?: boolean }) => boolean;
```
-This 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.
+This API can be used to toggle sidebar, optionally opening a specific sidebar tab. It returns whether the sidebar was toggled on or off. If the `force` flag passed, it will force the sidebar to be toggled either on/off.
-This 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.
+This API is especially useful when you render a custom [``](/docs/@excalidraw/excalidraw/api/children-components/sidebar), and you want to toggle it from your app based on a user action.
## resetCursor
@@ -389,3 +392,51 @@ This API is especially useful when you render a custom sidebar using [`renderSid
```
This API can be used to reset to default mouse cursor.
+
+## onChange
+
+```tsx
+(
+ callback: (
+ elements: readonly ExcalidrawElement[],
+ appState: AppState,
+ files: BinaryFiles,
+ ) => void
+) => () => void
+```
+
+Subscribes to change events, similar to [`props.onChange`](/docs/@excalidraw/excalidraw/api/props#onchange).
+
+Returns an unsubscribe function.
+
+## onPointerDown
+
+```tsx
+(
+ callback: (
+ activeTool: AppState["activeTool"],
+ pointerDownState: PointerDownState,
+ event: React.PointerEvent,
+ ) => void,
+) => () => void
+```
+
+Subscribes to canvas `pointerdown` events.
+
+Returns an unsubscribe function.
+
+## onPointerUp
+
+```tsx
+(
+ callback: (
+ activeTool: AppState["activeTool"],
+ pointerDownState: PointerDownState,
+ event: PointerEvent,
+ ) => void,
+) => () => void
+```
+
+Subscribes to canvas `pointerup` events.
+
+Returns an unsubscribe function.
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx
index 7d79128f0..0fec6ea02 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx
@@ -1,18 +1,18 @@
# initialData
-{ elements?: ExcalidrawElement[], appState?: AppState }
+{ elements?: ExcalidrawElement[], appState?: AppState }
This helps to load Excalidraw with `initialData`. It must be an object or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to an object containing the below optional fields.
| Name | Type | Description |
| --- | --- | --- |
-| `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114) | The `elements` with which `Excalidraw` should be mounted. |
-| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95) | The `AppState` with which `Excalidraw` should be mounted. |
+| `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | The `elements` with which `Excalidraw` should be mounted. |
+| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) | The `AppState` with which `Excalidraw` should be mounted. |
| `scrollToContent` | `boolean` | This attribute indicates whether to `scroll` to the nearest element to center once `Excalidraw` is mounted. By default, it will not scroll the nearest element to the center. Make sure you pass `initialData.appState.scrollX` and `initialData.appState.scrollY` when `scrollToContent` is false so that scroll positions are retained |
-| `libraryItems` | [LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L247) | Promise<[LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200)> | This library items with which `Excalidraw` should be mounted. |
-| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L82) | The `files` added to the scene. |
+| `libraryItems` | [LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L247) | Promise<[LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L200)> | This library items with which `Excalidraw` should be mounted. |
+| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L82) | The `files` added to the scene. |
You might want to use this when you want to load excalidraw with some initial elements and app state.
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
index a871874c5..766c723e4 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
@@ -1,11 +1,11 @@
# Props
-All `props` are *optional*.
+All `props` are _optional_.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
-| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` | `null` | Promise | `null` | The initial data with which app loads. |
-| [`ref`](/docs/@excalidraw/excalidraw/api/props/ref) | `object` | _ | `Ref` to be passed to Excalidraw |
+| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` | `null` | Promise | `null` | The initial data with which app loads. |
+| [`excalidrawAPI`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api) | `function` | _ | Callback triggered with the excalidraw api once rendered |
| [`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. |
@@ -17,26 +17,27 @@ All `props` are *optional*.
| [`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 |
| [`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) |
+| [`UIOptions`](/docs/@excalidraw/excalidraw/api/props/ui-options) | `object` | [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/constants.ts#L151) | To customise UI options. Currently we support customising [`canvas actions`](/docs/@excalidraw/excalidraw/api/props/ui-options#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 |
+| [`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 ` 
+ 
+
+ 
+
@@ -70,7 +73,7 @@ The Excalidraw editor (npm package) supports:
## Excalidraw.com
-The app hosted at [excalidraw.com](https://excalidraw.com) is a minimal showcase of what you can build with Excalidraw. Its [source code](https://github.com/excalidraw/excalidraw/tree/master/src/excalidraw-app) is part of this repository as well, and the app features:
+The app hosted at [excalidraw.com](https://excalidraw.com) is a minimal showcase of what you can build with Excalidraw. Its [source code](https://github.com/excalidraw/excalidraw/tree/master/excalidraw-app) is part of this repository as well, and the app features:
- 📡 PWA support (works offline).
- 🤼 Real-time collaboration.
@@ -82,7 +85,7 @@ We'll be adding these features as drop-in plugins for the npm package in the fut
## Quick start
-Install the [Excalidraw npm package](https://www.npmjs.com/package/@excalidraw/excalidraw):
+**Note:** following instructions are for installing the Excalidraw [npm package](https://www.npmjs.com/package/@excalidraw/excalidraw) when integrating Excalidraw into your own app. To run the repository locally for development, please refer to our [Development Guide](https://docs.excalidraw.com/docs/introduction/development).
```
npm install react react-dom @excalidraw/excalidraw
@@ -94,7 +97,7 @@ or via yarn
yarn add react react-dom @excalidraw/excalidraw
```
-Don't forget to check out our [Documentation](https://docs.excalidraw.com)!
+Check out our [documentation](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/installation) for more details!
## Contributing
diff --git a/crowdin.yml b/crowdin.yml
index a08b939c6..ccb8a17aa 100644
--- a/crowdin.yml
+++ b/crowdin.yml
@@ -1,3 +1,3 @@
files:
- - source: /src/locales/en.json
- translation: /src/locales/%locale%.json
+ - source: /packages/excalidraw/locales/en.json
+ translation: /packages/excalidraw/locales/%locale%.json
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
index 706adb594..06bb1cbaf 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
@@ -17,5 +17,6 @@ Below are the currently supported components:
- [MainMenu](/docs/@excalidraw/excalidraw/api/children-components/main-menu)
- [WelcomeScreen](/docs/@excalidraw/excalidraw/api/children-components/welcome-screen)
+- [Sidebar](/docs/@excalidraw/excalidraw/api/children-components/sidebar)
- [Footer](/docs/@excalidraw/excalidraw/api/children-components/footer)
- [LiveCollaborationTrigger](/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger)
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
index 262681895..3831268f0 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
@@ -16,7 +16,6 @@ function App() {
className="custom-footer"
onClick={() => alert("This is dummy footer")}
>
- {" "}
custom footer
@@ -35,7 +34,7 @@ Open the `Menu` in the below playground and you will see the `custom footer` ren
```jsx live noInline
const MobileFooter = ({}) => {
const device = useDevice();
- if (device.isMobile) {
+ if (device.editor.isMobile) {
return (