> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/excalidraw/excalidraw/llms.txt
> Use this file to discover all available pages before exploring further.
# UI Components API
> Complete API reference for Excalidraw UI components including MainMenu, Sidebar, Footer, and more
# UI Components API
Excalidraw provides a set of composable UI components that can be used to customize the editor interface. These components can be passed as children to the main `Excalidraw` component.
## Import
```jsx theme={null}
import {
MainMenu,
Sidebar,
Footer,
WelcomeScreen,
Button,
LiveCollaborationTrigger,
Stats,
DefaultSidebar,
Ellipsify,
TTDDialog,
TTDDialogTrigger,
TTDStreamFetch,
DiagramToCodePlugin,
CommandPalette,
useEditorInterface,
useStylesPanelMode,
} from "@excalidraw/excalidraw";
```
## MainMenu
The `MainMenu` component provides a customizable dropdown menu accessed via a hamburger icon.
### Props
Menu items and components to display in the dropdown. Can include `MainMenu.Item`, `MainMenu.ItemLink`, `MainMenu.DefaultItems.*`, `MainMenu.Separator`, `MainMenu.Group`, and `MainMenu.Sub`.
Callback fired when any menu item is selected (clicked on).
```typescript theme={null}
onSelect?: (event: Event) => void;
```
### Subcomponents
#### MainMenu.Item
A clickable menu item that triggers an action.
```jsx theme={null}
}
shortcut="⌘K"
>
Menu Item Label
```
Callback when item is clicked.
```typescript theme={null}
onSelect: () => void;
```
Icon to display before the label.
Keyboard shortcut to display (e.g., "⌘K", "Ctrl+S").
Label content for the menu item.
#### MainMenu.ItemLink
A menu item that opens a link in a new tab.
```jsx theme={null}
}
shortcut="⌘L"
>
External Link
```
URL to open when clicked.
Icon to display before the label.
Keyboard shortcut to display.
Label content for the menu item.
#### MainMenu.ItemCustom
A fully custom menu item with complete control over rendering.
```jsx theme={null}
{/* Your custom content */}
```
Custom content to render.
#### MainMenu.Separator
A visual separator between menu items.
```jsx theme={null}
```
No props.
#### MainMenu.Group
Groups related menu items together.
```jsx theme={null}
Item 1Item 2
```
Menu items to group together.
#### MainMenu.Sub
Creates a submenu.
```jsx theme={null}
}>
Sub Item 1Sub Item 2
```
Label for the submenu trigger.
Icon to display before the label.
Menu items to display in the submenu.
#### MainMenu.Trigger
Custom trigger component to open the menu (overrides default hamburger icon).
```jsx theme={null}
```
Custom trigger element.
### Default Items
Excalidraw provides pre-built menu items accessible via `MainMenu.DefaultItems`:
Opens a file picker to load a scene from a .excalidraw file.
```jsx theme={null}
```
Saves the current scene to the active file (requires File System Access API).
```jsx theme={null}
```
Opens the export dialog to save as PNG, SVG, or JSON.
```jsx theme={null}
```
Quickly export the canvas as an image.
```jsx theme={null}
```
Opens the help dialog showing keyboard shortcuts.
```jsx theme={null}
```
Clears all elements from the canvas.
```jsx theme={null}
```
Toggles between light and dark themes.
```jsx theme={null}
```
Opens a color picker to change the canvas background.
```jsx theme={null}
```
### Example
```jsx theme={null}
import { Excalidraw, MainMenu } from "@excalidraw/excalidraw";
function App() {
const handleCustomAction = () => {
console.log("Custom action triggered");
};
return (
);
}
```
## Sidebar
The `Sidebar` component provides a customizable sidebar that can be docked or floating.
### Props
Unique name for the sidebar. Used to identify and control the sidebar state.
```typescript theme={null}
name: SidebarName; // string
```
Sidebar content including `Sidebar.Header`, `Sidebar.Tabs`, `Sidebar.Tab`, etc.
Called on sidebar open/close or tab change.
```typescript theme={null}
onStateChange?: (state: { name: string; tab?: string } | null) => void;
```
**Parameters:**
* `state` - Current open sidebar state, or `null` if closed
Supply alongside `docked` prop to make the sidebar user-dockable.
```typescript theme={null}
onDock?: (docked: boolean) => void;
```
Controls whether the sidebar is docked. Must be used with `onDock` to enable user docking.
```typescript theme={null}
docked?: boolean;
```
Additional CSS class name for styling.
### Subcomponents
#### Sidebar.Header
Header component for the sidebar with title and optional dock/close buttons.
```jsx theme={null}
My Sidebar
```
Header content (typically a title).
#### Sidebar.Trigger
Button to open/close the sidebar.
```jsx theme={null}
}
title="Open Sidebar"
/>
```
Name of the sidebar to trigger (must match the Sidebar's `name` prop).
```typescript theme={null}
name: SidebarName;
```
Optional tab name to open when triggering the sidebar.
```typescript theme={null}
tab?: SidebarTabName;
```
Icon to display in the trigger button.
Tooltip text for the trigger button.
Additional CSS class name.
Callback when the trigger is clicked.
```typescript theme={null}
onToggle?: (open: boolean) => void;
```
Inline styles for the trigger button.
#### Sidebar.Tabs
Container for sidebar tabs.
```jsx theme={null}
Tab 1 ContentTab 2 Content
```
`Sidebar.Tab` components.
#### Sidebar.Tab
Individual tab content.
```jsx theme={null}
Tab content goes here
```
Unique identifier for the tab.
```typescript theme={null}
tab: SidebarTabName;
```
Tab content.
#### Sidebar.TabTriggers
Container for tab trigger buttons.
```jsx theme={null}
Tab 1Tab 2
```
`Sidebar.TabTrigger` components.
#### Sidebar.TabTrigger
Button to switch between tabs.
```jsx theme={null}
Tab Label
```
Tab identifier to activate.
```typescript theme={null}
tab: SidebarTabName;
```
Tab trigger label.
### Example
```jsx theme={null}
import { useState } from "react";
import { Excalidraw, Sidebar } from "@excalidraw/excalidraw";
function App() {
const [docked, setDocked] = useState(true);
return (
);
}
```
## Footer
The `Footer` component renders the bottom toolbar with zoom controls and undo/redo buttons. It's exported for use when building custom layouts, but is typically rendered automatically by Excalidraw.
```jsx theme={null}
import { Footer } from "@excalidraw/excalidraw";
```
The Footer component is usually rendered automatically. You only need to import it if you're building a completely custom layout.
## WelcomeScreen
The `WelcomeScreen` component displays a welcome message when the canvas is empty.
### Props
Custom welcome screen content. If not provided, renders default hints and center content.
### Subcomponents
#### WelcomeScreen.Center
Central welcome message area.
```jsx theme={null}
Welcome to My App!
```
**Sub-subcomponents:**
* `WelcomeScreen.Center.Logo` - Excalidraw logo
* `WelcomeScreen.Center.Heading` - Custom heading text
* `WelcomeScreen.Center.Menu` - Container for menu items
* `WelcomeScreen.Center.MenuItemLoadScene` - Load scene button
* `WelcomeScreen.Center.MenuItemHelp` - Help button
* `WelcomeScreen.Center.MenuItemLiveCollaborationTrigger` - Collaboration button
#### WelcomeScreen.Hints
UI hints around the editor.
```jsx theme={null}
```
**Available hints:**
* `WelcomeScreen.Hints.MenuHint` - Points to main menu
* `WelcomeScreen.Hints.ToolbarHint` - Points to toolbar
* `WelcomeScreen.Hints.HelpHint` - Points to help button
### Example
```jsx theme={null}
import { Excalidraw, WelcomeScreen } from "@excalidraw/excalidraw";
function App() {
return (
Start Drawing Amazing Diagrams!
);
}
```
## Button
A generic button component that follows Excalidraw's design system.
### Props
Callback when button is clicked.
```typescript theme={null}
onSelect: () => void;
```
Button content (text, icons, etc.).
HTML button type.
Whether button is in active/selected state.
Additional CSS class name for styling.
All standard HTML button attributes are supported (disabled, style, aria-\*, etc.).
### Example
```jsx theme={null}
import { Button } from "@excalidraw/excalidraw";
function MyComponent() {
const handleClick = () => {
console.log("Button clicked");
};
return (
);
}
```
## LiveCollaborationTrigger
A button component for triggering live collaboration mode, displaying the share icon and active collaborator count.
### Props
Whether collaboration mode is active.
```typescript theme={null}
isCollaborating: boolean;
```
Callback when the button is clicked.
```typescript theme={null}
onSelect: () => void;
```
Editor interface details for responsive behavior.
```typescript theme={null}
editorInterface?: EditorInterface;
```
All standard HTML button attributes are supported.
### Example
```jsx theme={null}
import { useState } from "react";
import { Excalidraw, LiveCollaborationTrigger } from "@excalidraw/excalidraw";
function App() {
const [isCollaborating, setIsCollaborating] = useState(false);
const handleCollaboration = () => {
setIsCollaborating(!isCollaborating);
// Your collaboration logic here
};
return (
);
}
```
## Complete Example
Here's a comprehensive example using multiple UI components together:
```jsx theme={null}
import { useState } from "react";
import {
Excalidraw,
MainMenu,
Sidebar,
WelcomeScreen,
LiveCollaborationTrigger,
Button,
} from "@excalidraw/excalidraw";
function App() {
const [isCollaborating, setIsCollaborating] = useState(false);
const [sidebarDocked, setSidebarDocked] = useState(true);
const handleExport = () => {
console.log("Export triggered");
};
return (
{/* Main Menu */}
Export to Cloud
{/* Custom Sidebar */}
ToolsShapesAssets
);
}
export default App;
```
## Styling
All UI components can be styled using CSS classes:
```css theme={null}
/* MainMenu */
.main-menu-trigger { }
.main-menu { }
.main-menu-item { }
/* Sidebar */
.excalidraw-sidebar { }
.excalidraw-sidebar.sidebar--docked { }
/* Button */
.excalidraw-button { }
.excalidraw-button.selected { }
/* LiveCollaborationTrigger */
.collab-button { }
.collab-button.active { }
.CollabButton-collaborators { }
```
## Stats
The `Stats` component displays canvas statistics and element properties in a floating panel. It provides detailed information about selected elements and the overall scene.
### Props
The Excalidraw app instance.
```typescript theme={null}
app: AppClassProperties;
```
Callback when the stats panel is closed.
```typescript theme={null}
onClose: () => void;
```
Render custom statistics in the panel.
```typescript theme={null}
renderCustomStats?: (
elements: readonly NonDeletedExcalidrawElement[],
appState: AppState
) => React.ReactNode;
```
### Subcomponents
#### Stats.StatsRow
Renders a row in the stats panel.
```jsx theme={null}
Width
100
```
Number of columns in the row grid.
Whether this row is a heading.
#### Stats.StatsRows
Container for multiple stat rows with optional ordering.
```jsx theme={null}
{/* Multiple StatsRow components */}
```
Display order of this stats group.
### Example
```jsx theme={null}
import { Stats } from "@excalidraw/excalidraw";
function CustomStats() {
const renderCustomStats = (elements, appState) => (
Custom Stats
Total Elements
{elements.length}
);
return (
);
}
```
## DefaultSidebar
The `DefaultSidebar` component provides the default sidebar with library and search functionality.
### Props
Custom sidebar tabs to add to the default sidebar.
Whether the sidebar is docked.
Callback when sidebar dock state changes. Pass `false` to disable docking.
```typescript theme={null}
onDock?: ((docked: boolean) => void) | false;
```
Additional CSS class name.
### Subcomponents
#### DefaultSidebar.Trigger
Trigger button for the default sidebar.
```jsx theme={null}
}
title="Open Sidebar"
/>
```
#### DefaultSidebar.TabTriggers
Container for adding custom tab triggers to the default sidebar.
```jsx theme={null}
My Tab
```
### Example
```jsx theme={null}
import { Excalidraw, DefaultSidebar, Sidebar } from "@excalidraw/excalidraw";
function App() {
return (
Custom tab content
);
}
```
## Ellipsify
A utility component that adds text ellipsis overflow handling.
### Props
Content to ellipsify.
All standard HTML span attributes are supported.
### Example
```jsx theme={null}
import { Ellipsify } from "@excalidraw/excalidraw";
This is a very long text that will be truncated with ellipsis
```
## TTDDialog
Text-to-Diagram dialog component for AI-powered diagram generation.
### Props
Callback when text is submitted for diagram generation.
```typescript theme={null}
onTextSubmit: (props: {
prompt: string;
sessionId: string;
}) => Promise<{
generatedResponse: string;
error: Error | null;
}>;
```
Render custom welcome screen content.
```typescript theme={null}
renderWelcomeScreen?: () => React.ReactNode;
```
Render custom warning message.
```typescript theme={null}
renderWarning?: () => React.ReactNode;
```
Adapter for persisting chat history.
```typescript theme={null}
persistenceAdapter: {
load: () => Promise;
save: (chats: SavedChats) => Promise;
clear: () => Promise;
};
```
### Subcomponents
#### TTDDialog.WelcomeMessage
Default welcome message component.
```jsx theme={null}
```
### Example
```jsx theme={null}
import { Excalidraw, TTDDialog } from "@excalidraw/excalidraw";
function App() {
const handleTextSubmit = async ({ prompt }) => {
// Call your AI API
const response = await fetch("/api/generate-diagram", {
method: "POST",
body: JSON.stringify({ prompt }),
});
const data = await response.json();
return {
generatedResponse: data.mermaidCode,
error: null,
};
};
const persistenceAdapter = {
load: async () => {
const saved = localStorage.getItem("ttd-chats");
return saved ? JSON.parse(saved) : null;
},
save: async (chats) => {
localStorage.setItem("ttd-chats", JSON.stringify(chats));
},
clear: async () => {
localStorage.removeItem("ttd-chats");
},
};
return (
);
}
```
## TTDDialogTrigger
Trigger button to open the Text-to-Diagram dialog.
### Props
Custom button label. Defaults to "Text to Diagram".
Custom icon for the trigger button.
### Example
```jsx theme={null}
import { MainMenu, TTDDialogTrigger } from "@excalidraw/excalidraw";
Generate Diagram with AI
```
## TTDStreamFetch
Utility function for streaming text-to-diagram API responses.
```typescript theme={null}
function TTDStreamFetch(options: {
url: string;
messages: readonly LLMMessage[];
onChunk?: (chunk: string) => void;
extractRateLimits?: boolean;
signal?: AbortSignal;
onStreamCreated?: () => void;
}): Promise<{
generatedResponse?: string;
error: Error | null;
rateLimit?: number;
rateLimitRemaining?: number;
}>;
```
### Parameters
API endpoint URL for streaming.
Array of messages to send to the LLM.
Callback for each chunk of streamed text.
```typescript theme={null}
onChunk?: (chunk: string) => void;
```
Whether to extract rate limit headers from the response.
AbortSignal for cancelling the request.
Callback when the stream is created.
### Example
```jsx theme={null}
import { TTDStreamFetch } from "@excalidraw/excalidraw";
const controller = new AbortController();
const result = await TTDStreamFetch({
url: "/api/generate-diagram",
messages: [
{ role: "user", content: "Create a flowchart for user authentication" }
],
onChunk: (chunk) => {
console.log("Received chunk:", chunk);
},
signal: controller.signal,
});
if (!result.error) {
console.log("Generated:", result.generatedResponse);
}
```
## DiagramToCodePlugin
Plugin component for adding diagram-to-code conversion functionality.
### Props
Function to generate code from the diagram.
```typescript theme={null}
generate: (opts: {
elements: readonly NonDeletedExcalidrawElement[];
files: BinaryFiles;
appState: AppState;
frameId?: string;
}) => Promise<{
code: string;
language: string;
}>;
```
### Example
```jsx theme={null}
import { Excalidraw, DiagramToCodePlugin } from "@excalidraw/excalidraw";
function App() {
const generateCode = async ({ elements, frameId }) => {
// Your code generation logic
const code = await convertElementsToCode(elements);
return {
code,
language: "typescript",
};
};
return (
);
}
```
## CommandPalette
Command palette component for quick access to editor actions via keyboard shortcuts.
### Props
Custom commands to add to the palette.
```typescript theme={null}
interface CommandPaletteItem {
label: string;
category: string;
icon?: JSX.Element;
shortcut?: string;
keywords?: string[];
viewMode?: boolean;
predicate?: boolean | PredicateFunction;
perform: (opts: {
actionManager: ActionManager;
event: React.MouseEvent | React.KeyboardEvent | KeyboardEvent;
}) => void;
}
```
### Default Items
The `CommandPalette.defaultItems` export provides access to pre-built command items:
```jsx theme={null}
import { CommandPalette } from "@excalidraw/excalidraw";
// Available default items include:
// - exportImage
// - loadScene
// - clearCanvas
// - changeViewBackgroundColor
// And more...
```
### Example
```jsx theme={null}
import { Excalidraw, CommandPalette } from "@excalidraw/excalidraw";
function App() {
const customCommands = [
{
label: "Export to Cloud",
category: "Export",
icon: ,
keywords: ["save", "upload"],
perform: ({ actionManager }) => {
// Your export logic
console.log("Exporting to cloud...");
},
},
];
return (
);
}
```
The command palette opens with `Cmd/Ctrl + Shift + P` or `Cmd/Ctrl + /`.
## Hooks
### useEditorInterface
Hook to access the editor's interface information including form factor and sidebar visibility.
```typescript theme={null}
function useEditorInterface(): {
formFactor: "desktop" | "tablet" | "phone";
isSidebarDocked: boolean;
};
```
**Example:**
```jsx theme={null}
import { useEditorInterface } from "@excalidraw/excalidraw";
function MyComponent() {
const editorInterface = useEditorInterface();
if (editorInterface.formFactor === "phone") {
return ;
}
return ;
}
```
### useStylesPanelMode
Hook to get the current styles panel mode derived from the editor interface.
```typescript theme={null}
function useStylesPanelMode(): "inline" | "popover";
```
**Example:**
```jsx theme={null}
import { useStylesPanelMode } from "@excalidraw/excalidraw";
function MyComponent() {
const mode = useStylesPanelMode();
return (
{/* Your component content */}
);
}
```
## See Also
* [Excalidraw Component API](/api/excalidraw-component) - Main component API reference
* [MainMenu](/components/main-menu) - MainMenu usage guide
* [Sidebar](/components/sidebar) - Sidebar usage guide
* [WelcomeScreen](/components/welcome-screen) - WelcomeScreen usage guide
* [Customization Guide](/guides/customization) - Customize component appearance