Data Types

Type definitions for data import/export and binary files

ImportedDataState

Data structure for importing Excalidraw scenes. All fields are optional to allow partial imports.

type · string

Type identifier for the data format

version · number

Version number of the data format

source · string

Source application or identifier

elements · readonly ExcalidrawElement[] | null

Array of elements to import, or null

appState · Partial<AppState> | null

Partial application state to import. Can include legacy AppState properties:

• isSidebarDocked (deprecated) maps to defaultSidebarDockedPreference

scrollToContent · boolean

Whether to scroll to the imported content after loading

libraryItems · LibraryItems_anyVersion

Library items to import (supports v1 and v2 formats)

files · BinaryFiles

Binary files (images, etc.) associated with the elements

ExportedDataState

Data structure for exporting Excalidraw scenes. This is a stricter version of ImportedDataState with required fields.

type · string · required

Type identifier, typically "excalidraw"

version · number · required

Version number of the Excalidraw format

source · string · required

Source application identifier

elements · readonly ExcalidrawElement[] · required

Array of all elements in the scene

appState · ReturnType<typeof cleanAppStateForExport> · required

Cleaned application state with only exportable properties

files · BinaryFiles | undefined · required

Binary files associated with the scene, or undefined if none

BinaryFileData

Represents a binary file (typically an image) in Excalidraw.

mimeType · ValueOf<typeof IMAGE_MIME_TYPES> | typeof MIME_TYPES.binary · required

MIME type of the file. Can be an image type or generic binary

id · FileId · required

Unique identifier for the file (branded string type)

dataURL · DataURL · required

Data URL containing the file contents (branded string type)

created · number · required

Epoch timestamp in milliseconds when the file was created

lastRetrieved · number

Epoch timestamp in milliseconds when the file was last retrieved from storage. Used to determine whether to delete unused files from storage

version · number

Version of the file. Used to determine whether the file dataURL has changed (e.g., as part of restore due to schema update)

BinaryFileMetadata

Binary file data without the actual data URL (useful for listing files without loading full data).

type BinaryFileMetadata = Omit<BinaryFileData, "dataURL">

mimeType · string · required

MIME type of the file

id · FileId · required

File identifier

created · number · required

Creation timestamp

lastRetrieved · number

Last retrieved timestamp

version · number

File version

BinaryFiles

A record mapping element IDs to their associated binary file data.

type BinaryFiles = Record<ExcalidrawElement["id"], BinaryFileData>

Library Types

LibraryItem

Represents a reusable component in the library (v2 format).

id · string · required

Unique identifier for the library item

status · 'published' | 'unpublished' · required

Publication status of the library item

elements · readonly NonDeleted<ExcalidrawElement>[] · required

Array of elements that make up this library item

created · number · required

Timestamp in epoch milliseconds when the item was created

name · string

Optional name for the library item

error · string

Error message if the library item failed to load

LibraryItems

Array of library items (v2 format).

type LibraryItems = readonly LibraryItem[]

LibraryItem_v1 (Deprecated)

Legacy v1 library item format. Do not use outside of migration paths.

type LibraryItem_v1 = readonly NonDeleted<ExcalidrawElement>[]

LibraryItems_v1 (Deprecated)

Legacy v1 library items array. Do not use outside of migration paths.

type LibraryItems_v1 = readonly LibraryItem_v1[]

LibraryItems_anyVersion

Union type supporting both v1 and v2 library formats for backward compatibility.

type LibraryItems_anyVersion = LibraryItems | LibraryItems_v1

ExportedLibraryData

Data structure for exporting library data.

type · string · required

Type identifier, typically "excalidrawlib"

version · typeof VERSIONS.excalidrawLibrary · required

Version number of the library format

source · string · required

Source application identifier

libraryItems · LibraryItems · required

Array of library items (v2 format)

ImportedLibraryData

Data structure for importing library data. Supports both current and legacy formats.

type · string

Type identifier

version · number

Version number

source · string

Source application identifier

libraryItems · LibraryItems

Library items in v2 format

library · LibraryItems

Deprecated (v1) - Legacy library format

ExcalidrawLibraryIds

Helper type for tracking library item IDs.

itemIds · LibraryItem['id'][] · required

Array of library item IDs

SceneData

Data structure for updating the scene, used with the updateScene API method.

elements · ImportedDataState['elements']

Elements to update in the scene

appState · ImportedDataState['appState']

Application state to update

collaborators · Map<SocketId, Collaborator>

Collaborators to update

captureUpdate · CaptureUpdateActionType

Whether to capture this update in history for undo/redo

ExcalidrawInitialDataState

Extended import data state used when initializing Excalidraw.

type ExcalidrawInitialDataState = Merge<
  ImportedDataState,
  {
    libraryItems?: MaybePromise<Required<ImportedDataState>["libraryItems"]>
  }
>

Inherits all properties from ImportedDataState but allows libraryItems to be a Promise.

Branded Types

These are string types with runtime branding for type safety:

DataURL

String representing a data URL (base64 encoded file data).

type DataURL = string & { _brand: "DataURL" }

FileId

String representing a unique file identifier.

type FileId = string & { _brand: "FileId" }

SocketId

String representing a WebSocket connection identifier.

type SocketId = string & { _brand: "SocketId" }

Legacy Types

LegacyAppState

Map of deprecated AppState keys for migration purposes.

isSidebarDocked · [boolean, 'defaultSidebarDockedPreference']

Deprecated #6213 - Maps to defaultSidebarDockedPreference. TODO: remove 23-06-01

The LegacyAppState type is a helper for downstream abstractions during data migration. Do not consume it directly in new code.

Usage Examples

Importing Data

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

const importData: ImportedDataState = {
  type: "excalidraw",
  version: 2,
  source: "my-app",
  elements: [...],
  appState: {
    viewBackgroundColor: "#ffffff",
    currentItemStrokeColor: "#000000"
  },
  files: {
    "file-id-123": {
      mimeType: "image/png",
      id: "file-id-123",
      dataURL: "data:image/png;base64,...",
      created: Date.now()
    }
  }
};

Working with Binary Files

import { BinaryFiles, BinaryFileData } from "@excalidraw/excalidraw";

const files: BinaryFiles = {};

const imageFile: BinaryFileData = {
  mimeType: "image/png",
  id: "image-123" as FileId,
  dataURL: "data:image/png;base64,iVBORw0KG..." as DataURL,
  created: Date.now(),
  lastRetrieved: Date.now(),
  version: 1
};

files["element-id"] = imageFile;

Exporting Data

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

const exportedData: ExportedDataState = {
  type: "excalidraw",
  version: 2,
  source: "https://excalidraw.com",
  elements: excalidrawAPI.getSceneElements(),
  appState: cleanAppStateForExport(excalidrawAPI.getAppState()),
  files: excalidrawAPI.getFiles()
};

const json = JSON.stringify(exportedData);