Skip to main content

​
Overview

Excalidraw provides extensive customization options through props, allowing you to tailor the editor to your application’s needs. You can control UI elements, behavior, and visual appearance.

​
Theme Customization

​
Setting the Theme

Control the editor’s color scheme with the theme prop: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw theme="light" />
  );
}
When you don’t pass the theme prop, Excalidraw automatically shows a theme toggle button in the canvas actions.

​
UI Options

​
Canvas Actions

Customize which action buttons appear on the canvas using UIOptions.canvasActions: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      UIOptions={{
        canvasActions: {
          // Toggle specific actions
          changeViewBackgroundColor: true,
          clearCanvas: true,
          export: { saveFileToDisk: true },
          loadScene: false,
          saveToActiveFile: false,
          toggleTheme: null, // null = auto-determine based on theme prop
        },
      }}
    />
  );
}
From the source code at packages/excalidraw/index.tsx:76-87, when toggleTheme is null and theme is undefined, the theme toggle button is automatically enabled.

​
Tools Configuration

Control which tools are available: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      UIOptions={{
        tools: {
          image: false, // Disable image tool
        },
      }}
    />
  );
}

​
View Modes

​
View Mode

Disable editing and show the canvas in read-only mode: 
import { Excalidraw } from "@excalidraw/excalidraw";
import { useState } from "react";

function App() {
  const [viewModeEnabled, setViewModeEnabled] = useState(false);

  return (
    <>
      <button onClick={() => setViewModeEnabled(!viewModeEnabled)}>
        Toggle View Mode
      </button>
      <Excalidraw viewModeEnabled={viewModeEnabled} />
    </>
  );
}

​
Zen Mode

Hide UI elements for a distraction-free canvas: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw zenModeEnabled={true} />
  );
}

​
Grid Mode

Show a grid overlay on the canvas: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw gridModeEnabled={true} />
  );
}

​
Custom UI Components

​
Custom Top UI

Render custom components in the top left or right areas: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      renderTopRightUI={() => (
        <div style={{ padding: "10px" }}>
          <button>Custom Button</button>
        </div>
      )}
    />
  );
}

​
Custom Statistics

Add custom statistics to the stats dialog: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      renderCustomStats={(elements, appState) => (
        <div>
          <h3>Custom Stats</h3>
          <p>Total elements: {elements.length}</p>
          <p>Zoom level: {appState.zoom.value}x</p>
        </div>
      )}
    />
  );
}

​
Behavior Configuration

​
Auto Focus

Automatically focus the canvas on mount: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw autoFocus={true} />
  );
}

​
Keyboard Handling

Control whether keyboard shortcuts work globally: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      handleKeyboardGlobally={true}
      // When true, keyboard shortcuts work even when canvas is not focused
    />
  );
}
Be careful when enabling handleKeyboardGlobally as it may conflict with your application’s keyboard shortcuts.

​
Scroll Detection

Control scroll behavior detection: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      detectScroll={true}
      onScrollChange={(scrollX, scrollY) => {
        console.log("Scroll changed:", { scrollX, scrollY });
      }}
    />
  );
}

​
Library Configuration

​
Library Return URL

Customize the URL users are redirected to after using the library: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      libraryReturnUrl="https://myapp.com/editor"
      onLibraryChange={(items) => {
        console.log("Library changed:", items);
      }}
    />
  );
}

​
AI Features

​
Enabling AI

Control AI-powered features: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      aiEnabled={true}
      // Set to false to disable AI features
    />
  );
}
AI features are enabled by default. From the source at packages/excalidraw/index.tsx:149, aiEnabled defaults to true unless explicitly set to false.

​
Advanced Customization

​
Custom Embeddable Validation

Control which embeddables are allowed: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      validateEmbeddable={(link) => {
        // Only allow YouTube embeds
        return link.includes("youtube.com");
      }}
      renderEmbeddable={(element, appState) => {
        // Custom embed rendering
        return <div>Custom Embed</div>;
      }}
    />
  );
}

​
Custom Scrollbars

Render custom scrollbars: 
import { Excalidraw } from "@excalidraw/excalidraw";

function App() {
  return (
    <Excalidraw
      renderScrollbars={(options) => {
        // Render custom scrollbar components
        return null; // Return null to use default
      }}
    />
  );
}

​
Next Steps

Theming

Learn about advanced theme customization

Export

Customize export functionality

Storage

Implement data persistence

Embedding

Embed Excalidraw in your app