Element Utilities

Utility functions for creating, mutating, and working with Excalidraw elements.

Import

import {
  // Element creation
  newElement,
  newTextElement,
  newLinearElement,
  newArrowElement,
  newImageElement,
  newFrameElement,
  
  // Element mutation
  mutateElement,
  newElementWith,
  bumpVersion,
  
  // Element queries
  getNonDeletedElements,
  getSceneVersion,
  hashElementsVersion,
  hashString,
  
  // Element bounds
  getElementAbsoluteCoords,
  getElementBounds,
  getCommonBounds,
  getVisibleSceneBounds,
  
  // Bounding box utilities
  elementsOverlappingBBox,
  isElementInsideBBox,
  elementPartiallyOverlapsWithOrContainsBBox,
  
  // Data utilities
  getDataURL,
  
  // Library utilities
  parseLibraryTokensFromUrl,
  useHandleLibrary,
  
  // Text utilities
  setCustomTextMetricsProvider,
  
  // Types
  CaptureUpdateAction,
} from "@excalidraw/excalidraw";

Element Creation

newElement

Creates a new generic Excalidraw element.

function newElement(
  opts: {
    type: ExcalidrawGenericElement["type"];
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawGenericElement>

string

required

Element type (e.g., “rectangle”, “ellipse”, “diamond”)

number

required

X coordinate of the element

number

required

Y coordinate of the element

number

default:"0"

Width of the element

number

default:"0"

Height of the element

Radians

default:"0"

Rotation angle in radians

string

Stroke color for the element

string

Background fill color

string

Fill style (“solid”, “hachure”, “cross-hatch”)

number

Width of the stroke

number

Roughness level for hand-drawn appearance

number

Opacity value (0-100)

ExcalidrawElement

The newly created element with all properties initialized

Example:

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

const rectangle = newElement({
  type: "rectangle",
  x: 100,
  y: 100,
  width: 200,
  height: 150,
  strokeColor: "#000000",
  backgroundColor: "#ffffff",
  fillStyle: "hachure",
  strokeWidth: 2,
  roughness: 1,
  opacity: 100,
});

newTextElement

Creates a new text element with automatic dimension calculations.

function newTextElement(
  opts: {
    text: string;
    fontSize?: number;
    fontFamily?: FontFamilyValues;
    textAlign?: TextAlign;
    verticalAlign?: VerticalAlign;
    containerId?: string | null;
    lineHeight?: number;
    autoResize?: boolean;
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawTextElement>

string

required

Text content to display

number

Font size in pixels

FontFamilyValues

Font family identifier (FONT_FAMILY constant)

'left' | 'center' | 'right'

Horizontal text alignment

'top' | 'middle'

Vertical text alignment

string | null

ID of container element (for bound text)

boolean

default:"true"

Whether text should auto-resize

Example:

import { newTextElement, FONT_FAMILY } from "@excalidraw/excalidraw";

const textElement = newTextElement({
  text: "Hello, World!",
  x: 100,
  y: 100,
  fontSize: 20,
  fontFamily: FONT_FAMILY.Virgil,
  textAlign: "center",
  strokeColor: "#000000",
});

newLinearElement

Creates a line or arrow element.

function newLinearElement(
  opts: {
    type: "line" | "arrow";
    points?: LocalPoint[];
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawLinearElement>

'line' | 'arrow'

required

Type of linear element

LocalPoint[]

Array of points [x, y] defining the line path

Example:

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

const line = newLinearElement({
  type: "line",
  x: 100,
  y: 100,
  points: [
    [0, 0],
    [100, 50],
    [200, 100],
  ],
  strokeColor: "#000000",
});

newArrowElement

Creates an arrow element with optional arrowheads.

function newArrowElement(
  opts: {
    type: "arrow";
    startArrowhead?: Arrowhead | null;
    endArrowhead?: Arrowhead | null;
    points?: LocalPoint[];
    elbowed?: boolean;
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawArrowElement>

Arrowhead | null

Arrowhead style for start point (“arrow”, “dot”, “bar”, etc.)

Arrowhead | null

Arrowhead style for end point

boolean

Whether the arrow should use elbow routing

Example:

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

const arrow = newArrowElement({
  type: "arrow",
  x: 100,
  y: 100,
  points: [
    [0, 0],
    [200, 0],
  ],
  startArrowhead: null,
  endArrowhead: "arrow",
  strokeColor: "#000000",
});

newImageElement

Creates an image element.

function newImageElement(
  opts: {
    type: "image";
    fileId?: string | null;
    status?: "pending" | "saved" | "error";
    scale?: [number, number];
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawImageElement>

string | null

ID of the file in BinaryFiles

'pending' | 'saved' | 'error'

Loading status of the image

[number, number]

Scale factors [x, y] for the image

newFrameElement

Creates a frame element for grouping.

function newFrameElement(
  opts: {
    name?: string;
  } & ElementConstructorOpts
): NonDeleted<ExcalidrawFrameElement>

string | null

Optional name for the frame

Element Mutation

mutateElement

Mutates an existing element with updates and bumps its version.

function mutateElement<TElement extends ExcalidrawElement>(
  element: TElement,
  elementsMap: ElementsMap,
  updates: ElementUpdate<TElement>,
  options?: {
    isDragging?: boolean;
  }
): TElement

ExcalidrawElement

required

The element to mutate

ElementsMap

required

Map of all elements (for context)

Partial<TElement>

required

Properties to update (excludes ‘id’ and ‘updated’)

boolean

Whether the element is being dragged

TElement

The mutated element with updated version and versionNonce

Example:

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

mutateElement(element, elementsMap, {
  x: 150,
  y: 200,
  width: 300,
});

newElementWith

Creates a new element instance with updates (immutable operation).

function newElementWith<TElement extends ExcalidrawElement>(
  element: TElement,
  updates: ElementUpdate<TElement>,
  force?: boolean
): TElement

ExcalidrawElement

required

The base element

Partial<TElement>

required

Properties to update

boolean

default:"false"

Force regeneration even if no changes detected

TElement

New element instance with updates applied

Example:

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

const updatedElement = newElementWith(element, {
  backgroundColor: "#ff0000",
  opacity: 80,
});

bumpVersion

Bumps element version, versionNonce, and updated timestamp.

function bumpVersion<T extends ExcalidrawElement>(
  element: T,
  version?: number
): T

ExcalidrawElement

required

The element to bump

number

Optional specific version to set (will be incremented by 1)

Example:

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

bumpVersion(element);

Element Queries

getNonDeletedElements

Filters out deleted elements from an array.

function getNonDeletedElements<T extends ExcalidrawElement>(
  elements: readonly T[]
): readonly NonDeleted<T>[]

readonly ExcalidrawElement[]

required

Array of elements to filter

NonDeleted<ExcalidrawElement>[]

Array of non-deleted elements

Example:

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

const activeElements = getNonDeletedElements(allElements);

getSceneVersion

Calculates the scene version by summing element versions.

function getSceneVersion(elements: readonly ExcalidrawElement[]): number

readonly ExcalidrawElement[]

required

Elements to calculate version from

number

Sum of all element versions

Note: This function is deprecated. Use hashElementsVersion instead for better performance.

hashElementsVersion

Generates a hash of elements’ versionNonce values using the djb2 algorithm.

function hashElementsVersion(elements: ElementsMapOrArray): number

ElementsMapOrArray

required

Elements to hash (array or Map)

number

Unsigned 32-bit integer hash

Example:

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

const versionHash = hashElementsVersion(elements);

hashString

Hashes a string using the djb2 algorithm.

function hashString(s: string): number

string

required

String to hash

number

Unsigned 32-bit integer hash

Element Bounds

getElementAbsoluteCoords

Gets absolute coordinates of an element in scene coordinates.

function getElementAbsoluteCoords(
  element: ExcalidrawElement,
  elementsMap: ElementsMap,
  includeBoundText?: boolean
): [number, number, number, number, number, number]

ExcalidrawElement

required

The element to get coordinates for

ElementsMap

required

Map of all elements

boolean

default:"false"

Whether to include bound text in calculations

[x1, y1, x2, y2, cx, cy]

Array containing: [x1, y1, x2, y2, centerX, centerY]

Example:

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

const [x1, y1, x2, y2, cx, cy] = getElementAbsoluteCoords(
  element,
  elementsMap
);
console.log(`Bounds: (${x1}, ${y1}) to (${x2}, ${y2})`);
console.log(`Center: (${cx}, ${cy})`);

getElementBounds

Gets the axis-aligned bounding box for an element.

function getElementBounds(
  element: ExcalidrawElement,
  elementsMap: ElementsMap,
  nonRotated?: boolean
): Bounds

ExcalidrawElement

required

The element to get bounds for

ElementsMap

required

Map of all elements

boolean

default:"false"

Whether to get bounds without rotation

[minX, minY, maxX, maxY]

Bounding box coordinates

getCommonBounds

Gets the common bounding box for multiple elements.

function getCommonBounds(
  elements: ElementsMapOrArray,
  elementsMap?: ElementsMap
): Bounds

ElementsMapOrArray

required

Elements to get common bounds for

ElementsMap

Optional elements map for context

[minX, minY, maxX, maxY]

Common bounding box containing all elements

Example:

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

const [minX, minY, maxX, maxY] = getCommonBounds(selectedElements);
const width = maxX - minX;
const height = maxY - minY;

getVisibleSceneBounds

Gets the visible bounds of the canvas viewport in scene coordinates.

function getVisibleSceneBounds(state: {
  scrollX: number;
  scrollY: number;
  width: number;
  height: number;
  zoom: { value: number };
}): SceneBounds

number

required

Horizontal scroll offset

number

required

Vertical scroll offset

number

required

Canvas width

number

required

Canvas height

{ value: number }

required

Current zoom value

[sceneX, sceneY, sceneX2, sceneY2]

Visible scene bounds

Element Text

refreshTextDimensions

Recalculates text element dimensions based on content and container.

function refreshTextDimensions(
  textElement: ExcalidrawTextElement,
  container: ExcalidrawTextContainer | null,
  elementsMap: ElementsMap,
  text?: string
): { text: string; x: number; y: number; width: number; height: number } | undefined

ExcalidrawTextElement

required

The text element to refresh

ExcalidrawTextContainer | null

required

Container element (if text is bound)

ElementsMap

required

Map of all elements

string

Optional text override

object

Updated text, position, and dimensions

Bounding Box Utilities

elementsOverlappingBBox

Finds elements that overlap with, contain, or are inside a bounding box.

function elementsOverlappingBBox(opts: {
  elements: readonly NonDeletedExcalidrawElement[];
  bounds: Bounds | ExcalidrawElement;
  errorMargin?: number;
  type: "overlap" | "contain" | "inside";
}): readonly NonDeletedExcalidrawElement[];

readonly NonDeletedExcalidrawElement[]

required

Elements to check against the bounding box.

Bounds | ExcalidrawElement

required

Bounding box as [x1, y1, x2, y2] or an element to use its bounds.

number

default:"0"

Safety offset in pixels to expand the bounding box.

'overlap' | 'contain' | 'inside'

required

overlap: Elements overlapping or inside bounds
contain: Elements inside bounds or bounds inside elements
inside: Elements inside bounds only

NonDeletedExcalidrawElement[]

Array of elements matching the criteria.

Example:

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

// Find elements overlapping a selection box
const selectedElements = elementsOverlappingBBox({
  elements: allElements,
  bounds: [100, 100, 400, 400],
  type: "overlap",
});

// Find elements completely inside a frame
const elementsInFrame = elementsOverlappingBBox({
  elements: allElements,
  bounds: frameElement,
  type: "inside",
});

isElementInsideBBox

Checks if an element is inside a bounding box.

function isElementInsideBBox(
  element: NonDeletedExcalidrawElement,
  bbox: Bounds,
  eitherDirection?: boolean
): boolean;

NonDeletedExcalidrawElement

required

Element to check.

Bounds

required

Bounding box as [x1, y1, x2, y2].

boolean

default:"false"

If true, also returns true if bbox is inside element.

boolean

true if element is inside the bounding box.

Example:

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

const bounds = [0, 0, 500, 500];
const isInside = isElementInsideBBox(element, bounds);

if (isInside) {
  console.log("Element is inside the bounds");
}

elementPartiallyOverlapsWithOrContainsBBox

Checks if an element partially overlaps with or contains a bounding box.

function elementPartiallyOverlapsWithOrContainsBBox(
  element: NonDeletedExcalidrawElement,
  bbox: Bounds
): boolean;

NonDeletedExcalidrawElement

required

Element to check.

Bounds

required

Bounding box as [x1, y1, x2, y2].

boolean

true if element overlaps or contains the bounding box.

Example:

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

const dragBox = [100, 100, 200, 200];
const overlaps = elementPartiallyOverlapsWithOrContainsBBox(element, dragBox);

if (overlaps) {
  console.log("Element should be selected");
}

Data Utilities

getDataURL

Converts a Blob or File to a Data URL (async).

function getDataURL(file: Blob | File): Promise<DataURL>;

Blob | File

required

File or Blob to convert.

DataURL

Base64-encoded data URL string.

Example:

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

const file = new File(["Hello"], "test.txt", { type: "text/plain" });
const dataURL = await getDataURL(file);
console.log(dataURL); // "data:text/plain;base64,SGVsbG8="

Library Utilities

parseLibraryTokensFromUrl

Extracts library installation URL and ID token from the current page URL.

function parseLibraryTokensFromUrl(): {
  libraryUrl: string;
  idToken: string | null;
} | null;

object | null

Object with libraryUrl and idToken, or null if not found.

Example:

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

// URL: https://excalidraw.com/#addLibrary=https://example.com/lib.excalidrawlib
const tokens = parseLibraryTokensFromUrl();

if (tokens) {
  console.log("Library URL:", tokens.libraryUrl);
  console.log("ID Token:", tokens.idToken);
}

useHandleLibrary

Hook for handling library loading, updates, and persistence.

function useHandleLibrary(opts: {
  excalidrawAPI: ExcalidrawImperativeAPI | null;
  validateLibraryUrl?: (url: string) => boolean;
} & (
  | { getInitialLibraryItems?: () => MaybePromise<LibraryItemsSource> }
  | {
      adapter: LibraryPersistenceAdapter;
      migrationAdapter?: LibraryMigrationAdapter;
    }
)): void;

ExcalidrawImperativeAPI | null

required

Excalidraw API instance.

function

Custom validator for library installation URLs.

validateLibraryUrl?: (url: string) => boolean;

LibraryPersistenceAdapter

Adapter for persisting library to storage.

interface LibraryPersistenceAdapter {
  load(metadata: { source: "load" | "save" }): Promise<{
    libraryItems: LibraryItems;
  } | null>;
  save(data: { libraryItems: LibraryItems }): Promise<void>;
}

LibraryMigrationAdapter

Optional adapter for migrating from legacy storage.

interface LibraryMigrationAdapter {
  load(): Promise<{ libraryItems: LibraryItems } | null>;
  clear(): Promise<void>;
}

Example:

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

function MyEditor() {
  const [excalidrawAPI, setExcalidrawAPI] = useState(null);

  useHandleLibrary({
    excalidrawAPI,
    adapter: {
      async load() {
        const data = localStorage.getItem("excalidraw-library");
        return data ? JSON.parse(data) : null;
      },
      async save({ libraryItems }) {
        localStorage.setItem(
          "excalidraw-library",
          JSON.stringify({ libraryItems })
        );
      },
    },
  });

  return <Excalidraw excalidrawAPI={(api) => setExcalidrawAPI(api)} />;
}

Text Utilities

setCustomTextMetricsProvider

Sets a custom text metrics provider for measuring text dimensions.

function setCustomTextMetricsProvider(
  provider: (
    text: string,
    font: string
  ) => {
    width: number;
    height: number;
  }
): void;

function

required

Function that measures text and returns width/height.

provider: (text: string, font: string) => {
  width: number;
  height: number;
};

Example:

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

// Use a custom text measurement implementation
setCustomTextMetricsProvider((text, font) => {
  const canvas = document.createElement("canvas");
  const ctx = canvas.getContext("2d");
  ctx.font = font;
  
  const metrics = ctx.measureText(text);
  
  return {
    width: metrics.width,
    height: metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent,
  };
});

Types

CaptureUpdateAction

Enum-like object that controls when element updates are captured in the undo/redo history.

const CaptureUpdateAction = {
  IMMEDIATELY: "IMMEDIATELY",
  NEVER: "NEVER",
  EVENTUALLY: "EVENTUALLY",
};

type CaptureUpdateActionType = ValueOf<typeof CaptureUpdateAction>;

Values:

IMMEDIATELY - Updates are immediately undoable. Use for most local updates.
NEVER - Updates never make it to undo/redo stack. Use for remote updates or scene initialization.
EVENTUALLY - Updates will eventually be captured as part of a future increment.

Example:

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

// When updating scene programmatically
excalidrawAPI.updateScene({
  elements: newElements,
  captureUpdate: CaptureUpdateAction.NEVER, // Don't add to undo stack
});

// When updating in response to user action
excalidrawAPI.updateScene({
  elements: modifiedElements,
  captureUpdate: CaptureUpdateAction.IMMEDIATELY, // Allow undo
});

​Element Utilities

​Import

​Element Creation

​newElement

​newTextElement

​newLinearElement

​newArrowElement

​newImageElement

​newFrameElement

​Element Mutation

​mutateElement

​newElementWith

​bumpVersion

​Element Queries

​getNonDeletedElements

​getSceneVersion

​hashElementsVersion

​hashString

​Element Bounds

​getElementAbsoluteCoords

​getElementBounds

​getCommonBounds

​getVisibleSceneBounds

​Element Text

​refreshTextDimensions

​Bounding Box Utilities

​elementsOverlappingBBox

​isElementInsideBBox

​elementPartiallyOverlapsWithOrContainsBBox

​Data Utilities

​getDataURL

​Library Utilities

​parseLibraryTokensFromUrl

​useHandleLibrary

​Text Utilities

​setCustomTextMetricsProvider

​Types

​CaptureUpdateAction

​See Also

Element Utilities

Import

Element Creation

newElement

newTextElement

newLinearElement

newArrowElement

newImageElement

newFrameElement

Element Mutation

mutateElement

newElementWith

bumpVersion

Element Queries

getNonDeletedElements

getSceneVersion

hashElementsVersion

hashString

Element Bounds

getElementAbsoluteCoords

getElementBounds

getCommonBounds

getVisibleSceneBounds

Element Text

refreshTextDimensions

Bounding Box Utilities

elementsOverlappingBBox

isElementInsideBBox

elementPartiallyOverlapsWithOrContainsBBox

Data Utilities

getDataURL

Library Utilities

parseLibraryTokensFromUrl

useHandleLibrary

Text Utilities

setCustomTextMetricsProvider

Types

CaptureUpdateAction

See Also