excalidraw/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md

slug

slug
/@excalidraw/excalidraw/api/utils

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?: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L80">ExcalidrawElement</a>): 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.

const MobileFooter = ({}) => {
  const device = useDevice();
  if (device.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

Name	Type	Description
isSmScreen	boolean	Set to true when the device small screen is small (Width < 640px )
isMobile	boolean	Set to true when the device is mobile
isTouchScreen	boolean	Set to true for touch devices
canDeviceFitSidebar	boolean	Implies whether there is enough space to fit the sidebar