Skip to main content

​
InitialData

The initialData prop allows you to populate the Excalidraw canvas with elements, app state, and files when the component mounts.

​
Type Definition

type ExcalidrawInitialDataState = {
  elements?: readonly ExcalidrawElement[] | null;
  appState?: Partial<AppState> | null;
  scrollToContent?: boolean;
  libraryItems?: LibraryItems | Promise<LibraryItems>;
  files?: BinaryFiles;
};

type InitialDataProp = 
  | ExcalidrawInitialDataState
  | (() => Promise<ExcalidrawInitialDataState | null>)
  | Promise<ExcalidrawInitialDataState | null>
  | null;
The initialData prop accepts:
  • A static object with initial data
  • A Promise that resolves to initial data
  • A function returning a Promise (useful for lazy loading)
  • null (starts with empty canvas)

​
Properties

​
elements
readonly ExcalidrawElement[] | null
Array of elements to render on the canvas.Each element must be a valid Excalidraw element with all required properties. Elements will be automatically restored and validated during initialization.
​
appState
Partial<AppState> | null
Partial app state to initialize the editor with.You only need to provide the properties you want to override from the default state. Common properties include:
​
scrollToContent
boolean
default:"false"
When true, automatically scrolls and zooms the canvas to fit all elements in view after initialization.Useful when loading scenes with elements that may be positioned far from the origin.
​
libraryItems
LibraryItems | Promise<LibraryItems>
Library items to preload into the element library.Can be a static array or a Promise that resolves to library items. This allows you to provide default templates or frequently used element groups.
​
files
BinaryFiles
Binary file data for images and other file-based elements.Maps file IDs to their binary data. Required if your elements include images.

​
Usage Examples

​
Static Initial Data

Provide initial data as a static object: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      initialData={{
        elements: [
          {
            type: "rectangle",
            x: 100,
            y: 100,
            width: 200,
            height: 100,
            // ... other required properties
          },
        ],
        appState: {
          viewBackgroundColor: "#ffffff",
          gridModeEnabled: true,
        },
        scrollToContent: true,
      }}
    />
  );
}

​
Async Loading

Load initial data asynchronously from an API: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  const loadInitialData = async () => {
    const response = await fetch("/api/diagram/123");
    const data = await response.json();
    
    return {
      elements: data.elements,
      appState: data.appState,
      files: data.files,
      scrollToContent: true,
    };
  };
  
  return <Excalidraw initialData={loadInitialData} />;
}

​
Lazy Loading with Promise

Use a Promise directly for lazy initialization: 
import { Excalidraw } from "@excalidraw/excalidraw";

const initialDataPromise = fetch("/api/diagram")
  .then(res => res.json())
  .then(data => ({
    elements: data.elements,
    appState: data.appState,
    scrollToContent: true,
  }));

function App() {
  return <Excalidraw initialData={initialDataPromise} />;
}

​
Loading from Local Storage

Restore previous session from local storage: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  const loadFromStorage = () => {
    const saved = localStorage.getItem("excalidraw-state");
    if (!saved) return null;
    
    try {
      const parsed = JSON.parse(saved);
      return {
        elements: parsed.elements || [],
        appState: parsed.appState || {},
        files: parsed.files || {},
      };
    } catch (error) {
      console.error("Failed to parse saved state", error);
      return null;
    }
  };
  
  return <Excalidraw initialData={loadFromStorage()} />;
}

​
With Library Items

Preload library with templates: 
import { Excalidraw } from "@excalidraw/excalidraw";

const libraryItems = [
  {
    id: "template-flowchart",
    status: "published" as const,
    created: Date.now(),
    name: "Flowchart Symbols",
    elements: [
      // Flowchart element templates
    ],
  },
  {
    id: "template-uml",
    status: "published" as const,
    created: Date.now(),
    name: "UML Diagrams",
    elements: [
      // UML element templates
    ],
  },
];

function App() {
  return (
    <Excalidraw
      initialData={{
        libraryItems,
        scrollToContent: false,
      }}
    />
  );
}

​
Important Notes

Element Restoration: Elements provided in initialData are automatically restored and validated. Missing or invalid properties are filled with defaults.
Required Properties: While the restoration process fills in missing properties, it’s recommended to provide complete element definitions to avoid unexpected behavior.
Async Loading: When using async loading (Promise or function), Excalidraw shows a loading state until the data resolves.
Memory Considerations: Loading large scenes with many elements or large binary files can impact performance. Consider lazy loading or pagination for very large datasets.

​
Type Imports

import type {
  ExcalidrawInitialDataState,
  ExcalidrawElement,
  AppState,
  BinaryFiles,
  LibraryItems,
  LibraryItem,
} from "@excalidraw/excalidraw";