diff options
Diffstat (limited to 'dev-docs/docs/@excalidraw/excalidraw/api/utils')
3 files changed, 784 insertions, 0 deletions
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx new file mode 100644 index 0000000..6337fe7 --- /dev/null +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx @@ -0,0 +1,196 @@ +--- +title: Export Utilities +id: "export" +--- + +:::info + +We're working on much improved export utilities. Stay tuned! + +::: + +### exportToCanvas + +**_Signature_** + +<pre> +exportToCanvas({<br/> + elements,<br/> + appState<br/> + getDimensions,<br/> + files,<br/> + exportPadding?: number;<br/> +}: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/utils/export.ts#L24">ExportOpts</a> +</pre> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `elements` | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | | The elements to be exported to canvas. | +| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/utils.ts#L23) | [Default App State](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/appState.ts#L17) | The app state of the scene. | +| [`getDimensions`](#getdimensions) | `function` | _ | A function which returns the `width`, `height`, and optionally `scale` (defaults to `1`), with which canvas is to be exported. | +| `maxWidthOrHeight` | `number` | _ | The maximum `width` or `height` of the exported image. If provided, `getDimensions` is ignored. | +| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L59) | _ | The files added to the scene. | +| `exportPadding` | `number` | `10` | The `padding` to be added on canvas. | + + +#### getDimensions + +```tsx +(width: number, height: number) => { + width: number, + height: number, + scale?: number +} +``` +A function which returns the `width`, `height`, and optionally `scale` (defaults to `1`), with which canvas is to be exported. + +**How to use** + +```js +import { exportToCanvas } from "@excalidraw/excalidraw"; +``` + +This function returns the canvas with the exported elements, appState and dimensions. + +```jsx live +function App() { + const [canvasUrl, setCanvasUrl] = useState(""); + const [excalidrawAPI, setExcalidrawAPI] = useState(null); + + return ( + <> + <button + className="custom-button" + onClick={async () => { + if (!excalidrawAPI) { + return + } + const elements = excalidrawAPI.getSceneElements(); + if (!elements || !elements.length) { + return + } + const canvas = await exportToCanvas({ + elements, + appState: { + ...initialData.appState, + exportWithDarkMode: false, + }, + files: excalidrawAPI.getFiles(), + getDimensions: () => { return {width: 350, height: 350}} + }); + const ctx = canvas.getContext("2d"); + ctx.font = "30px Virgil"; + ctx.strokeText("My custom text", 50, 60); + setCanvasUrl(canvas.toDataURL()); + }} + > + Export to Canvas + </button> + <div className="export export-canvas"> + <img src={canvasUrl} alt="" /> + </div> + <div style={{ height: "400px" }}> + <Excalidraw excalidrawAPI={(api) => setExcalidrawAPI(api)} +/> + </div> + </> + ) +} +``` + + +### exportToBlob + +**_Signature_** + +<pre> +exportToBlob(<br/> + opts: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/utils.ts#L14">ExportOpts</a> & {<br/> + mimeType?: string,<br/> + quality?: number,<br/> + exportPadding?: number;<br/> +}) +</pre> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `opts` | `object` | _ | This param is passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exporttocanvas) | +| `mimeType` | `string` | `image/png` | Indicates the image format. | +| `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. | +| `exportPadding` | `number` | `10` | The padding to be added on canvas. | + +**How to use** + +```js +import { exportToBlob } from "@excalidraw/excalidraw"; +``` + +Returns 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). + +### exportToSvg + +**_Signature_** + +<pre> +exportToSvg({<br/> + elements: + <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114"> + ExcalidrawElement[] + </a>,<br/> + appState: + <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95"> AppState + </a>,<br/> + exportPadding: number,<br/> + metadata: string,<br/> + files: + <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L59"> + BinaryFiles + </a>,<br/> +}); +</pre> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | | The elements to exported as `svg `| +| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/appState.ts#L11) | The `appState` of the scene | +| exportPadding | number | 10 | The `padding` to be added on canvas | +| files | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L64) | undefined | The `files` added to the scene. | + +This function returns a promise which resolves to `svg` of the exported drawing. + +### exportToClipboard + +**_Signature_** + +<pre> +exportToClipboard(<br/> + opts: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/utils.ts#L21">ExportOpts</a> & {<br/> + mimeType?: string,<br/> + quality?: number;<br/> + type: 'png' | 'svg' |'json'<br/> +}) +</pre> + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `opts` | | | This param is same as the params passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exporttocanvas). | +| `mimeType` | `string` | `image/png` | Indicates the image format, this will be used when exporting as `png`. | +| `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`. | +| `type` | 'png' | 'svg' | 'json' | _ | This determines the format to which the scene data should be `exported`. | + +**How to use** + +```js +import { exportToClipboard } from "@excalidraw/excalidraw"; +``` + +Copies the scene data in the specified format (determined by `type`) to clipboard. + +### Additional attributes of appState for export\* APIs + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `exportBackground` | `boolean` | `true` | Indicates whether `background` should be exported | +| `viewBackgroundColor` | `string` | `#fff` | The default background color | +| `exportWithDarkMode` | `boolean` | `false` | Indicates whether to export with `dark` mode | +| `exportEmbedScene` | `boolean` | `false` | Indicates whether scene data should be embedded in `svg/png`. This will increase the image size. | diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx new file mode 100644 index 0000000..2b4df2c --- /dev/null +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx @@ -0,0 +1,109 @@ +--- +title: Restore Utilities +id: "restore" +--- + +### restoreAppState + +**_Signature_** + +<pre> +restoreAppState(appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L34">ImportedDataState["appState"]</a>,<br/> localAppState: Partial<<a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a>> | null): <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a> +</pre> + +**_How to use_** + +```js +import { restoreAppState } from "@excalidraw/excalidraw"; +``` + +This function will make sure all the `keys` have appropriate `values` in [appState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) and if any key is missing, it will be set to its `default` value. + +When `localAppState` is supplied, it's used in place of values that are missing (`undefined`) in `appState` instead of the defaults. +Use this as a way to not override user's defaults if you persist them. +You can pass `null` / `undefined` if not applicable. + +### restoreElements + +**_Signature_** + +<pre> +restoreElements( + elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ImportedDataState["elements"]</a>,<br/> + localElements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a> | null | undefined): <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a>,<br/> + opts: { refreshDimensions?: boolean, repairBindings?: boolean, normalizeIndices?: boolean }<br/> +) +</pre> + +| Prop | Type | Description | +| ---- | ---- | ---- | +| `elements` | <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ImportedDataState["elements"]</a> | The `elements` to be restored | +| [`localElements`](#localelements) | <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a> | null | undefined | When `localElements` are supplied, they are used to ensure that existing restored elements reuse `version` (and increment it), and regenerate `versionNonce`. | +| [`opts`](#opts) | `Object` | The extra optional parameter to configure restored elements + +#### localElements + +When `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 update + +#### opts +The extra optional parameter to configure restored elements. It has the following attributes + +| Prop | Type | Description| +| --- | --- | ------| +| `refreshDimensions` | `boolean` | Indicates whether we should also _recalculate_ text element dimensions. Since this is a potentially costly operation, you may want to disable it if you restore elements in tight loops, such as during collaboration. | +| `repairBindings` |`boolean` | Indicates whether the _bindings_ for the elements should be repaired. This is to make sure there are no containers with non existent bound text element id and no bound text elements with non existent container id. | +| `normalizeIndices` |`boolean` | Indicates whether _fractional indices_ for the elements should be normalized. This is to prevent possible issues caused by using stale (too old, too long) indices. | + +**_How to use_** + +```js +import { restoreElements } from "@excalidraw/excalidraw"; +``` + +This function will make sure all properties of element is correctly set and if any attribute is missing, it will be set to its default value. + +Parameter `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. + +### restore + +**_Signature_** + +<pre> +restore( + data: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L34">ImportedDataState</a>,<br/> + localAppState: Partial<<a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a>> | null | undefined,<br/> + localElements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a> | null | undefined<br/>): <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L4">DataState</a><br/> + opts: { refreshDimensions?: boolean, repairBindings?: boolean, normalizeIndices?: boolean }<br/> + +) +</pre> + +See [`restoreAppState()`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/excalidraw/README.md#restoreAppState) about `localAppState`, and [`restoreElements()`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/excalidraw/README.md#restoreElements) about `localElements`. + +**_How to use_** + +```js +import { restore } from "@excalidraw/excalidraw"; +``` + +This 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). + +### restoreLibraryItems + +**_Signature_** + +<pre> +restoreLibraryItems(libraryItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L34">ImportedDataState["libraryItems"]</a>,<br/> +defaultStatus: "published" | "unpublished") +</pre> + +**_How to use_** + +```js +import { restoreLibraryItems } from "@excalidraw/excalidraw"; + +restoreLibraryItems(libraryItems, "unpublished"); +``` + +This function normalizes library items elements, adding missing values when needed. diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md b/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md new file mode 100644 index 0000000..69bd88a --- /dev/null +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md @@ -0,0 +1,479 @@ +--- +slug: /@excalidraw/excalidraw/api/utils +--- + +# Utils + +These are pure Javascript functions exported from the @excalidraw/excalidraw [`@excalidraw/excalidraw`](https://npmjs.com/@excalidraw/excalidraw). If you want to export your drawings in different formats eg `png`, `svg` and more you can check out [Export Utilities](/docs/@excalidraw/excalidraw/API/utils/export). If you want to restore your drawings you can check out [Restore Utilities](/docs/@excalidraw/excalidraw/API/utils/restore). + +### serializeAsJSON + +Takes 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/packages/excalidraw/data/json.ts#L42) source for details). + +If you want to overwrite the `source` field in the `JSON` string, you can set `window.EXCALIDRAW_EXPORT_SOURCE` to the desired value. + +**_Signature_** + +<pre> +serializeAsJSON({<br/> + elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a>,<br/> + appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a>,<br/> +}): string +</pre> + +**How to use** + +```js +import { serializeAsJSON } from "@excalidraw/excalidraw"; +``` + +### serializeLibraryAsJSON + +Takes the `library` items and returns a `JSON` string. + +If you want to overwrite the source field in the JSON string, you can set `window.EXCALIDRAW_EXPORT_SOURCE` to the desired value. + +**_Signature_** + +<pre> +serializeLibraryAsJSON( + libraryItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L200">LibraryItems[]</a>) +</pre> + +**How to use** + +```js +import { serializeLibraryAsJSON } from "@excalidraw/excalidraw"; +``` + +#### isInvisiblySmallElement + +Returns `true` if element is invisibly small (e.g. width & height are zero). + +**_Signature_** + +<pre> +isInvisiblySmallElement(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement</a>): boolean +</pre> + +**How to use** + +```js +import { isInvisiblySmallElement } from "@excalidraw/excalidraw"; +``` + +### loadFromBlob + +This function loads the scene data from the blob (or file). If you pass `localAppState`, `localAppState` value will be preferred over the `appState` derived from `blob`. Throws if blob doesn't contain valid scene data. + +**How to use** + +```js +import { loadFromBlob } from "@excalidraw/excalidraw"; + +const scene = await loadFromBlob(file, null, null); +excalidrawAPI.updateScene(scene); +``` + +**Signature** + +<pre> +loadFromBlob(<br/> + blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>,<br/> + localAppState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a> | null,<br/> + localElements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a> | null,<br/> + fileHandle?: FileSystemHandle | null <br/> +) => Promise<<a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/restore.ts#L61">RestoredDataState</a>> +</pre> + +### loadLibraryFromBlob + +This function loads the library from the blob. Additonally takes `defaultStatus` param which sets the default status for library item if not present, defaults to `unpublished`. + +**How to use ** + +```js +import { loadLibraryFromBlob } from "@excalidraw/excalidraw"; +``` + +**_Signature_** + +<pre> +loadLibraryFromBlob(blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>, defaultStatus: "published" | "unpublished") +</pre> + +### loadSceneOrLibraryFromBlob + +This function loads either scene or library data from the supplied blob. If the blob contains scene data, and you pass `localAppState`, `localAppState` value will be preferred over the `appState` derived from `blob`. + +:::caution + +Throws if blob doesn't contain valid `scene` data or `library` data. + +::: + +**How to use** + +```js showLineNumbers +import { loadSceneOrLibraryFromBlob, MIME_TYPES } from "@excalidraw/excalidraw"; + +const contents = await loadSceneOrLibraryFromBlob(file, null, null); +if (contents.type === MIME_TYPES.excalidraw) { + excalidrawAPI.updateScene(contents.data); +} else if (contents.type === MIME_TYPES.excalidrawlib) { + excalidrawAPI.updateLibrary(contents.data); +} +``` + +**_Signature_** + +<pre> +loadSceneOrLibraryFromBlob(<br/> + blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>,<br/> + localAppState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a> | null,<br/> + localElements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a> | null,<br/> + fileHandle?: FileSystemHandle | null<br/> +) => Promise<{ type: string, data: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/restore.ts#L53">RestoredDataState</a> | <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L33">ImportedLibraryState</a>}> +</pre> + +### getFreeDrawSvgPath + +This function returns the `free draw` svg path for the element. + +**How to use** + +```js +import { getFreeDrawSvgPath } from "@excalidraw/excalidraw"; +``` + +**Signature** + +<pre> +getFreeDrawSvgPath(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L182">ExcalidrawFreeDrawElement</a>) +</pre> + +### isLinearElement + +This function returns true if the element is `linear` type (`arrow` |`line`) else returns `false`. + +**How to use** + +```js +import { isLinearElement } from "@excalidraw/excalidraw"; +``` + +**Signature** + +<pre> +isLinearElement(elementType?: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L80">ExcalidrawElement</a>): boolean +</pre> + +### getNonDeletedElements + +This function returns an array of `deleted` elements. + +**How to use** + +```js +import { getNonDeletedElements } from "@excalidraw/excalidraw"; +``` + +**Signature** + +<pre> +getNonDeletedElements(elements:<a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114"> readonly ExcalidrawElement[]</a>): as readonly <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L125">NonDeletedExcalidrawElement[]</a> +</pre> + +### mergeLibraryItems + +This function merges two `LibraryItems` arrays, where unique items from `otherItems` are sorted first in the returned array. + +```js +import { mergeLibraryItems } from "@excalidraw/excalidraw"; +``` + +**_Signature_** + +<pre> +mergeLibraryItems(<br/> + localItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L250">LibraryItems</a>,<br/> + otherItems: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L200">LibraryItems</a><br/> +): <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L250">LibraryItems</a> +</pre> + +### parseLibraryTokensFromUrl + +Parses library parameters from URL if present (expects the `#addLibrary` hash key), and returns an object with the `libraryUrl` and `idToken`. Returns `null` if `#addLibrary` hash key not found. + +**How to use** + +```js +import { parseLibraryTokensFromUrl } from "@excalidraw/excalidraw"; +``` + +**Signature** + +```tsx +parseLibraryTokensFromUrl(): { + libraryUrl: string; + idToken: string | null; +} | null +``` + +### useHandleLibrary + +A hook that automatically imports library from url if `#addLibrary` hash key exists on initial load, or when it changes during the editing session (e.g. when a user installs a new library), and handles initial library load if `getInitialLibraryItems` getter is supplied. + +**How to use** + +```js +import { useHandleLibrary } from "@excalidraw/excalidraw"; + +export const App = () => { + // ... + useHandleLibrary({ excalidrawAPI }); +}; +``` + +**Signature** + +<pre> +useHandleLibrary(opts: {<br/> + excalidrawAPI: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L494">ExcalidrawAPI</a>,<br/> + getInitialLibraryItems?: () => <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L253">LibraryItemsSource</a><br/> +}); +</pre> + +In the future, we will be adding support for handling `library` persistence to `browser storage` (or elsewhere). + +### getSceneVersion + +This function returns the current `scene` version. + +**_Signature_** + +<pre> +getSceneVersion(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114">ExcalidrawElement[]</a>) +</pre> + +**How to use** + +```js +import { getSceneVersion } from "@excalidraw/excalidraw"; +``` + +### sceneCoordsToViewportCoords + +This function returns equivalent `viewport` coords for the provided `scene` coords in params. + +```js +import { sceneCoordsToViewportCoords } from "@excalidraw/excalidraw"; +``` + +**_Signature_** + +<pre> +sceneCoordsToViewportCoords({ sceneX: number, sceneY: number },<br/> + appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a><br/>): { x: number, y: number } +</pre> + +### viewportCoordsToSceneCoords + +This function returns equivalent `scene` coords for the provided `viewport` coords in params. + +```js +import { viewportCoordsToSceneCoords } from "@excalidraw/excalidraw"; +``` + +**_Signature_** + +<pre> +viewportCoordsToSceneCoords({ clientX: number, clientY: number },<br/> + appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95">AppState</a><br/>): {x: number, y: number} +</pre> + +### useDevice + +This hook can be used to check the type of device which is being used. It can only be used inside the `children` of `Excalidraw` component. + +Open the `main menu` in the below example to view the footer. + +```jsx live noInline +const MobileFooter = ({}) => { + const device = useDevice(); + if (device.editor.isMobile) { + return ( + <Footer> + <button + className="custom-footer" + style={{ marginLeft: "20px", height: "2rem" }} + onClick={() => alert("This is custom footer in mobile menu")} + > + custom footer + </button> + </Footer> + ); + } + return null; +}; +const App = () => ( + <div style={{ height: "400px" }}> + <Excalidraw> + <MainMenu> + <MainMenu.Item> Item1 </MainMenu.Item> + <MainMenu.Item> Item 2 </MainMenu.Item> + <MobileFooter /> + </MainMenu> + </Excalidraw> + </div> +); + +// Need to render when code is span across multiple components +// in Live Code blocks editor +render(<App />); +``` + +The `device` has the following `attributes`, some grouped into `viewport` and `editor` objects, per context. + +| Name | Type | Description | +| --- | --- | --- | +| `viewport.isMobile` | `boolean` | Set to `true` when viewport is in `mobile` breakpoint | +| `viewport.isLandscape` | `boolean` | Set to `true` when the viewport is in `landscape` mode | +| `editor.canFitSidebar` | `boolean` | Set to `true` if there's enough space to fit the `sidebar` | +| `editor.isMobile` | `boolean` | Set to `true` when editor container is in `mobile` breakpoint | +| `isTouchScreen` | `boolean` | Set to `true` for `touch` when touch event detected | + +### i18n + +To help with localization, we export the following. + +| name | type | +| --- | --- | +| `defaultLang` | `string` | +| `languages` | [`Language[]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L15) | +| `useI18n` | [`() => { langCode, t }`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L15) | + +```js +import { defaultLang, languages, useI18n } from "@excalidraw/excalidraw"; +``` + +#### defaultLang + +Default language code, `en`. + +#### languages + +List of supported language codes. You can pass any of these to `Excalidraw`'s [`langCode` prop](/docs/@excalidraw/excalidraw/api/props/#langcode). + +#### useI18n + +A hook that returns the current language code and translation helper function. You can use this to translate strings in the components you render as children of `<Excalidraw>`. + +```jsx live +function App() { + const { t } = useI18n(); + return ( + <div style={{ height: "500px" }}> + <Excalidraw> + <button + style={{ position: "absolute", zIndex: 10, height: "2rem" }} + onClick={() => window.alert(t("labels.madeWithExcalidraw"))} + > + {t("buttons.confirm")} + </button> + </Excalidraw> + </div> + ); +} +``` + +### getCommonBounds + +This util can be used to get the common bounds of the passed elements. + +**_Signature_** + +```ts +getCommonBounds( + elements: readonly ExcalidrawElement[] +): readonly [ + minX: number, + minY: number, + maxX: number, + maxY: number, +] +``` + +**_How to use_** + +```js +import { getCommonBounds } from "@excalidraw/excalidraw"; +``` + +### elementsOverlappingBBox + +To filter `elements` that are inside, overlap, or contain the `bounds` rectangle. + +The bounds check is approximate and does not precisely follow the element's shape. You can also supply `errorMargin` which effectively makes the `bounds` larger by that amount. + +This API has 3 `type`s of operation: `overlap`, `contain`, and `inside`: + +- `overlap` - filters elements that are overlapping or inside bounds. +- `contain` - filters elements that are inside bounds or bounds inside elements. +- `inside` - filters elements that are inside bounds. + +**_Signature_** + +<pre> +elementsOverlappingBBox(<br/> + elements: readonly NonDeletedExcalidrawElement[];<br/> + bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a> | ExcalidrawElement;<br/> + errorMargin?: number;<br/> + type: "overlap" | "contain" | "inside";<br/> +): NonDeletedExcalidrawElement[]; +</pre> + +**_How to use_** + +```js +import { elementsOverlappingBBox } from "@excalidraw/excalidraw"; +``` + +### isElementInsideBBox + +Lower-level API than `elementsOverlappingBBox` to check if a single `element` is inside `bounds`. If `eitherDirection=true`, returns `true` if `element` is fully inside `bounds` rectangle, or vice versa. When `false`, it returns `true` only for the former case. + +**_Signature_** + +<pre> +isElementInsideBBox(<br/> + element: NonDeletedExcalidrawElement,<br/> + bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a>,<br/> + eitherDirection = false,<br/> +): boolean +</pre> + +**_How to use_** + +```js +import { isElementInsideBBox } from "@excalidraw/excalidraw"; +``` + +### elementPartiallyOverlapsWithOrContainsBBox + +Checks if `element` is overlapping the `bounds` rectangle, or is fully inside. + +**_Signature_** + +<pre> +elementPartiallyOverlapsWithOrContainsBBox(<br/> + element: NonDeletedExcalidrawElement,<br/> + bounds: <a href="https://github.com/excalidraw/excalidraw/blob/9c425224c789d083bf16e0597ce4a429b9ee008e/src/element/bounds.ts#L37-L42">Bounds</a>,<br/> +): boolean +</pre> + +**_How to use_** + +```js +import { elementPartiallyOverlapsWithOrContainsBBox } from "@excalidraw/excalidraw"; +``` |