Utils

These are pure Javascript functions exported from the @excalidraw/excalidraw @excalidraw/excalidraw. If you want to export your drawings in different formats eg png, svg and more you can check out Export Utilities. If you want to restore your drawings you can check out Restore Utilities.

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() 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

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

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

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

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

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

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

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

import { isLinearElement } from "@excalidraw/excalidraw";

Signature

isLinearElement(elementType?: ExcalidrawElement): boolean

getNonDeletedElements

This function returns an array of deleted elements.

How to use

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.

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

import { parseLibraryTokensFromUrl } from "@excalidraw/excalidraw";

Signature

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

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

import { getSceneVersion } from "@excalidraw/excalidraw";

sceneCoordsToViewportCoords

This function returns equivalent viewport coords for the provided scene coords in params.

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.

import { viewportCoordsToSceneCoords } from "@excalidraw/excalidraw";

Signature

viewportCoordsToSceneCoords({ clientX: number, clientY: number },
  appState: AppState
): {x: number, y: number}

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.

Live Editor

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 />);

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 />);

Result

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[]`
`useI18n`	`() => { langCode, t }`

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.

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>.

Live Editor

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>
  );
}

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>
  );
}

Result

getCommonBounds

This util can be used to get the common bounds of the passed elements.

Signature

getCommonBounds(
  elements: readonly ExcalidrawElement[]
): readonly [
  minX: number,
  minY: number,
  maxX: number,
  maxY: number,
]

How to use

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 types 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

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

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

import { elementPartiallyOverlapsWithOrContainsBBox } from "@excalidraw/excalidraw";

Utils

serializeAsJSON​

serializeLibraryAsJSON​

isInvisiblySmallElement​

loadFromBlob​

loadLibraryFromBlob​

loadSceneOrLibraryFromBlob​

getFreeDrawSvgPath​

isLinearElement​

getNonDeletedElements​

mergeLibraryItems​

parseLibraryTokensFromUrl​

useHandleLibrary​

getSceneVersion​

sceneCoordsToViewportCoords​

viewportCoordsToSceneCoords​

useDevice​

i18n​

defaultLang​

languages​

useI18n​

getCommonBounds​

elementsOverlappingBBox​

isElementInsideBBox​

elementPartiallyOverlapsWithOrContainsBBox​

serializeAsJSON

serializeLibraryAsJSON

isInvisiblySmallElement

loadFromBlob

loadLibraryFromBlob

loadSceneOrLibraryFromBlob

getFreeDrawSvgPath

isLinearElement

getNonDeletedElements

mergeLibraryItems

parseLibraryTokensFromUrl

useHandleLibrary

getSceneVersion

sceneCoordsToViewportCoords

viewportCoordsToSceneCoords

useDevice

i18n

defaultLang

languages

useI18n

getCommonBounds

elementsOverlappingBBox

isElementInsideBBox

elementPartiallyOverlapsWithOrContainsBBox