# Excalidraw > slug: /@excalidraw/excalidraw/api/utils --- # Excalidraw Documentation # Source: https://github.com/excalidraw/excalidraw/blob/master/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md # Path: dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md --- 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_**
serializeAsJSON({
  elements: ExcalidrawElement[],
  appState: AppState,
}): string
**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_**
serializeLibraryAsJSON(
  libraryItems: LibraryItems[])
**How to use** ```js import { serializeLibraryAsJSON } from "@excalidraw/excalidraw"; ``` #### isInvisiblySmallElement Returns `true` if element is invisibly small (e.g. width & height are zero). **_Signature_**
isInvisiblySmallElement(element:  ExcalidrawElement): boolean
**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**
loadFromBlob(
  blob: Blob,
  localAppState: AppState | null,
  localElements: ExcalidrawElement[] | null,
  fileHandle?: FileSystemHandle | null
) => Promise<RestoredDataState>
### 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_**
loadLibraryFromBlob(blob: Blob, defaultStatus: "published" | "unpublished")
### 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_**
loadSceneOrLibraryFromBlob(
  blob: Blob,
  localAppState: AppState | null,
  localElements: ExcalidrawElement[] | null,
  fileHandle?: FileSystemHandle | null
) => Promise<{ type: string, data: RestoredDataState | ImportedLibraryState}>
### getFreeDrawSvgPath This function returns the `free draw` svg path for the element. **How to use** ```js import { getFreeDrawSvgPath } from "@excalidraw/excalidraw"; ``` **Signature**
getFreeDrawSvgPath(element: ExcalidrawFreeDrawElement)
### 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**
isLinearElement(elementType?: ExcalidrawElement): boolean
### getNonDeletedElements This function returns an array of `deleted` elements. **How to use** ```js import { getNonDeletedElements } from "@excalidraw/excalidraw"; ``` **Signature**
getNonDeletedElements(elements: readonly ExcalidrawElement[]): as readonly NonDeletedExcalidrawElement[]
### 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_**
mergeLibraryItems(
  localItems: LibraryItems,
  otherItems: LibraryItems
): LibraryItems
### 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**
useHandleLibrary(opts: {
  excalidrawAPI: ExcalidrawAPI,
  getInitialLibraryItems?: () => LibraryItemsSource
});
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_**
getSceneVersion(elements:  ExcalidrawElement[])
**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_**
sceneCoordsToViewportCoords({ sceneX: number, sceneY: number },
  appState: AppState
): { x: number, y: number }
### viewportCoordsToSceneCoords This function returns equivalent `scene` coords for the provided `viewport` coords in params. ```js import { viewportCoordsToSceneCoords } from "@excalidraw/excalidraw"; ``` **_Signature_**
viewportCoordsToSceneCoords({ clientX: number, clientY: number },
  appState: AppState
): {x: number, y: number}
### useEditorInterface 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 editorInterface = useEditorInterface(); if (editorInterface.formFactor === "phone") { return ( ); } return null; }; const App = () => (
Item1 Item 2
); // Need to render when code is span across multiple components // in Live Code blocks editor render(); ``` The `device` has the following `attributes`, some grouped into `viewport` and `editor` objects, per context. | Name | Type | Description | | ---- | ---- | ----------- | The `EditorInterface` object has the following properties: | Name | Type | Description | | --- | --- | --- | --- | --- | --- | | `formFactor` | `'phone' | 'tablet' | 'desktop'` | Indicates the device type based on screen size | | `desktopUIMode` | `'compact' | 'full'` | UI mode for desktop form factor | | `userAgent.raw` | `string` | Raw user agent string | | `userAgent.isMobileDevice` | `boolean` | True if device is mobile | | `userAgent.platform` | `'ios' | 'android' | 'other' | 'unknown'` | Device platform | | `isTouchScreen` | `boolean` | True if touch events are detected | | `canFitSidebar` | `boolean` | True if sidebar can fit in the viewport | | `isLandscape` | `boolean` | True if viewport is in landscape mode | ### 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 ``. ```jsx live function App() { const { t } = useI18n(); return (
); } ``` ### 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_**
elementsOverlappingBBox(
  elements: readonly NonDeletedExcalidrawElement[];
  bounds: Bounds | ExcalidrawElement;
  errorMargin?: number;
  type: "overlap" | "contain" | "inside";
): NonDeletedExcalidrawElement[];
**_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_**
isElementInsideBBox(
  element: NonDeletedExcalidrawElement,
  bounds: Bounds,
  eitherDirection = false,
): boolean
**_How to use_** ```js import { isElementInsideBBox } from "@excalidraw/excalidraw"; ``` ### elementPartiallyOverlapsWithOrContainsBBox Checks if `element` is overlapping the `bounds` rectangle, or is fully inside. **_Signature_**
elementPartiallyOverlapsWithOrContainsBBox(
  element: NonDeletedExcalidrawElement,
  bounds: Bounds,
): boolean
**_How to use_** ```js import { elementPartiallyOverlapsWithOrContainsBBox } from "@excalidraw/excalidraw"; ``` --- # Excalidraw Documentation # Source: https://github.com/excalidraw/excalidraw/blob/master/README.md # Path: README.md Excalidraw

Excalidraw Editor | Blog | Documentation | Excalidraw+

An open source virtual hand-drawn style whiteboard.
Collaborative and end-to-end encrypted.


Excalidraw is released under the MIT license. npm downloads/month PRs welcome! Chat on Discord Ask DeepWiki Follow Excalidraw on Twitter

Product showcase

Create beautiful hand-drawn like diagrams, wireframes, or whatever you like.

## Features The Excalidraw editor (npm package) supports: - 💯 Free & open-source. - 🎨 Infinite, canvas-based whiteboard. - ✍️ Hand-drawn like style. - 🌓 Dark mode. - 🏗️ Customizable. - 📷 Image support. - 😀 Shape libraries support. - 🌐 Localization (i18n) support. - 🖼️ Export to PNG, SVG & clipboard. - 💾 Open format - export drawings as an `.excalidraw` json file. - ⚒️ Wide range of tools - rectangle, circle, diamond, arrow, line, free-draw, eraser... - ➡️ Arrow-binding & labeled arrows. - 🔙 Undo / Redo. - 🔍 Zoom and panning support. ## 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/excalidraw-app) is part of this repository as well, and the app features: - 📡 PWA support (works offline). - 🤼 Real-time collaboration. - 🔒 End-to-end encryption. - 💾 Local-first support (autosaves to the browser). - 🔗 Shareable links (export to a readonly link you can share with others). We'll be adding these features as drop-in plugins for the npm package in the future. ## Quick start **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). Use `npm` or `yarn` to install the package. ```bash npm install react react-dom @excalidraw/excalidraw # or yarn add react react-dom @excalidraw/excalidraw ``` Check out our [documentation](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/installation) for more details! ## Contributing - Missing something or found a bug? [Report here](https://github.com/excalidraw/excalidraw/issues). - Want to contribute? Check out our [contribution guide](https://docs.excalidraw.com/docs/introduction/contributing) or let us know on [Discord](https://discord.gg/UexuTaE). - Want to help with translations? See the [translation guide](https://docs.excalidraw.com/docs/introduction/contributing#translating). ## Integrations - [VScode extension](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) - [npm package](https://www.npmjs.com/package/@excalidraw/excalidraw) ## Who's integrating Excalidraw [Google Cloud](https://googlecloudcheatsheet.withgoogle.com/architecture) • [Meta](https://meta.com/) • [CodeSandbox](https://codesandbox.io/) • [Obsidian Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) • [Replit](https://replit.com/) • [Slite](https://slite.com/) • [Notion](https://notion.so/) • [HackerRank](https://www.hackerrank.com/) • and many others ## Sponsors & support If you like the project, you can become a sponsor at [Open Collective](https://opencollective.com/excalidraw) or use [Excalidraw+](https://plus.excalidraw.com/). ## Thank you for supporting Excalidraw [](https://opencollective.com/excalidraw/tiers/sponsors/0/website) [](https://opencollective.com/excalidraw/tiers/sponsors/1/website) [](https://opencollective.com/excalidraw/tiers/sponsors/2/website) [](https://opencollective.com/excalidraw/tiers/sponsors/3/website) [](https://opencollective.com/excalidraw/tiers/sponsors/4/website) [](https://opencollective.com/excalidraw/tiers/sponsors/5/website) [](https://opencollective.com/excalidraw/tiers/sponsors/6/website) [](https://opencollective.com/excalidraw/tiers/sponsors/7/website) [](https://opencollective.com/excalidraw/tiers/sponsors/8/website) [](https://opencollective.com/excalidraw/tiers/sponsors/9/website) [](https://opencollective.com/excalidraw/tiers/sponsors/10/website) Last but not least, we're thankful to these companies for offering their services for free: [![Vercel](./.github/assets/vercel.svg)](https://vercel.com) [![Sentry](./.github/assets/sentry.svg)](https://sentry.io) [![Crowdin](./.github/assets/crowdin.svg)](https://crowdin.com)