UIOptions

Configuration reference for Excalidraw UI features and canvas actions

UIOptions

The UIOptions prop allows you to customize which UI features and canvas actions are available in the Excalidraw editor.

Type Definition

type UIOptions = Partial<{
  dockedSidebarBreakpoint: number;
  canvasActions: CanvasActions;
  tools: {
    image: boolean;
  };
  getFormFactor?: (
    editorWidth: number,
    editorHeight: number,
  ) => "mobile" | "desktop";
}>;

Properties

dockedSidebarBreakpoint · number

The viewport width (in pixels) below which the sidebar switches from docked to floating mode.

Allows you to control responsive behavior of the sidebar.

canvasActions · CanvasActions

Configuration object controlling which canvas actions are available.

See Canvas Actions below for details.

tools · object

Configuration for tool availability.

Show Properties

tools.image · boolean · default: "true"

When false, hides the image tool from the toolbar.

getFormFactor · function

Optional function to control the editor form factor and desktop UI mode from the host app.

If not provided, Excalidraw determines this automatically based on viewport size.

(editorWidth: number, editorHeight: number) => "mobile" | "desktop"

Show Example

UIOptions={{
  getFormFactor: (width, height) => {
    // Force mobile UI for narrow viewports
    return width < 768 ? "mobile" : "desktop";
  },
}}

Canvas Actions

The canvasActions object controls which actions are available in the canvas menu and UI.

type CanvasActions = Partial<{
  changeViewBackgroundColor: boolean;
  clearCanvas: boolean;
  export: false | ExportOpts;
  loadScene: boolean;
  saveToActiveFile: boolean;
  toggleTheme: boolean | null;
  saveAsImage: boolean;
}>;

Action Properties

changeViewBackgroundColor · boolean · default: "true"

When false, hides the canvas background color picker.

clearCanvas · boolean · default: "true"

When false, hides the “Clear canvas” action.

export · false | ExportOpts · default: "{ saveFileToDisk: true }"

Controls export functionality.

• false: Disables all export features
• ExportOpts: Configures export behavior (see Export Options)

loadScene · boolean · default: "true"

When false, hides the “Load scene” action (open file functionality).

saveToActiveFile · boolean · default: "true"

When false, hides the “Save to active file” action.

toggleTheme · boolean | null · default: "null"

Controls the theme toggle button.

• true: Shows the theme toggle
• false: Hides the theme toggle
• null: Default behavior (shows based on context)

saveAsImage · boolean · default: "true"

When false, hides the “Save as image” action.

Export Options

When canvasActions.export is an object, you can configure export behavior:

type ExportOpts = {
  saveFileToDisk?: boolean;
  onExportToBackend?: (
    exportedElements: readonly NonDeletedExcalidrawElement[],
    appState: UIAppState,
    files: BinaryFiles,
  ) => void;
  renderCustomUI?: (
    exportedElements: readonly NonDeletedExcalidrawElement[],
    appState: UIAppState,
    files: BinaryFiles,
    canvas: HTMLCanvasElement,
  ) => JSX.Element;
};

saveFileToDisk · boolean · default: "true"

When false, disables the ability to save exports directly to disk.

onExportToBackend · function

Custom handler for backend export. Called when user exports the canvas.

(exportedElements: readonly NonDeletedExcalidrawElement[],
 appState: UIAppState,
 files: BinaryFiles) => void

Show Example

onExportToBackend: async (elements, appState, files) => {
  await fetch("/api/export", {
    method: "POST",
    body: JSON.stringify({ elements, appState, files }),
  });
}

renderCustomUI · function

Custom UI renderer for the export dialog.

(exportedElements: readonly NonDeletedExcalidrawElement[],
 appState: UIAppState,
 files: BinaryFiles,
 canvas: HTMLCanvasElement) => JSX.Element

Default Values

Excalidraw uses these default values when UIOptions is not provided:

const DEFAULT_UI_OPTIONS = {
  canvasActions: {
    changeViewBackgroundColor: true,
    clearCanvas: true,
    export: { saveFileToDisk: true },
    loadScene: true,
    saveToActiveFile: true,
    toggleTheme: null,
    saveAsImage: true,
  },
  tools: {
    image: true,
  },
};

Usage Examples

Minimal UI

Disable most UI actions for a read-only or embedded experience:

<Excalidraw
  UIOptions={{
    canvasActions: {
      changeViewBackgroundColor: false,
      clearCanvas: false,
      export: false,
      loadScene: false,
      saveToActiveFile: false,
      saveAsImage: false,
    },
    tools: {
      image: false,
    },
  }}
/>

Custom Export Only

Enable custom backend export while disabling file downloads:

<Excalidraw
  UIOptions={{
    canvasActions: {
      export: {
        saveFileToDisk: false,
        onExportToBackend: async (elements, appState, files) => {
          // Send to your backend
          await saveToBackend(elements, appState, files);
        },
      },
    },
  }}
/>

Show Theme Toggle

Explicitly enable the theme toggle:

<Excalidraw
  UIOptions={{
    canvasActions: {
      toggleTheme: true,
    },
  }}
/>

Custom Form Factor Logic

Control when mobile vs desktop UI is used:

<Excalidraw
  UIOptions={{
    getFormFactor: (width, height) => {
      // Use mobile UI for portrait tablets
      if (width < 768 || (width < 1024 && height > width)) {
        return "mobile";
      }
      return "desktop";
    },
  }}
/>

Type Imports

import type {
  UIOptions,
  CanvasActions,
  ExportOpts,
} from "@excalidraw/excalidraw";