Element data and creation reference

This reference covers the element utilities used to build and process Excalidraw scenes programmatically. An element is a drawable object such as a shape, text, arrow, image, frame, or embed. The examples assume TypeScript and the @excalidraw/excalidraw package.

Create elements from skeletons

ExcalidrawElementSkeleton is a simplified input type with the minimum attributes needed to create elements. Use convertToExcalidrawElements before passing the result to initialData, updateScene, or another API that expects complete ExcalidrawElement values.

convertToExcalidrawElements

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

const elements = convertToExcalidrawElements([
  { type: "rectangle", x: 100, y: 120 },
  { type: "ellipse", x: 280, y: 120 },
  { type: "diamond", x: 460, y: 120 },
]);

The function returns fully qualified elements. ID regeneration also gives resulting instances new creation times. The skeleton API is documented as beta and may change before it becomes stable.

Supported shape examples include rectangle, ellipse, and diamond. Add supported element properties to decorate the shapes, then inspect the resulting elements before publishing them to a scene.

Filter scene elements

getVisibleElements

Returns non-deleted elements that are not invisibly small. Use it when computing visible bounds, presenting a scene summary, or exporting only meaningful content.

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

const visible = getVisibleElements(sceneElements);

getNonDeletedElements

Returns elements whose isDeleted flag is false. Unlike getVisibleElements, this utility does not remove elements solely because they are invisibly small.

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

const active = getNonDeletedElements(sceneElements);

Track and hash changes

hashElementsVersion

Hashes the versionNonce values in element order. Use it as a lightweight scene-version signal when order matters. The hash is not cryptographic and should not be used as an integrity or security check.

getSceneVersion

Adds element versions, but is deprecated and unsafe. Use hashElementsVersion for new code.

hashString

Computes a non-cryptographic string hash using the DJB2 algorithm. Use it for versioning-style comparisons only.

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

const sceneRevision = hashElementsVersion(sceneElements);
const labelRevision = hashString("diagram-summary");

Validate and normalize before use

Element utilities do not replace scene restoration. When elements come from a file, clipboard payload, or collaboration message, call restoreElements before inserting them so missing properties receive defaults and optional binding, dimension, and fractional-index repairs can be applied. See Export and restore utilities reference.

When merging imported elements with local elements, pass localElements to restoration so existing elements keep the appropriate incremented version and receive a regenerated versionNonce. This prevents version-based update detection from treating a newly imported element as stale.

Troubleshooting

A generated element does not render

Cause: a skeleton was passed directly to initialData or updateScene. Fix: run convertToExcalidrawElements first, then verify the result contains complete element properties.

A change detector misses an update

Cause: the deprecated version sum or a comparison that ignores element order was used. Fix: use hashElementsVersion on the current ordered collection and verify the hash changes after the update.

Invisible elements appear in a visible-only result

Cause: getNonDeletedElements removes deleted elements but keeps invisibly small ones. Fix: use getVisibleElements when the result is intended for display or bounds calculation.

Imported elements lose their update precedence

Cause: restoration was performed without the current localElements. Fix: pass the local collection to restoreElements and verify versions and versionNonce values on matching IDs.

Next step

For the serialized element and image-file container, see Excalidraw file and clipboard format. For applying a complete scene to the editor, see ExcalidrawAPI reference.