AppState
The complete application state interface for Excalidraw. This contains all UI state, canvas state, tool state, and user preferences.UI State
Context Menu
Current context menu state including items and position, or null if no context menu is shown
Dialogs and Modals
OpenDialog
required
Currently open dialog. Can be:
null- No dialog open{ name: "imageExport" | "help" | "jsonExport" }{ name: "ttd"; tab: "text-to-diagram" | "mermaid" }{ name: "commandPalette" }{ name: "settings" }{ name: "elementLinkSelector"; sourceElementId: string }
Currently open menu
OpenPopup
required
Currently open popup. Can be:
"canvasBackground""elementBackground""elementStroke""fontFamily""compactTextProperties""compactStrokeStyles""compactOtherProperties""compactArrowProperties"null
{ name: SidebarName; tab?: SidebarTabName } | null
required
Currently open sidebar with optional tab selection
PasteDialog
required
Paste dialog state:
{ shown: false; data: null }{ shown: true; data: Spreadsheet }
false | 'info' | 'editor'
required
Hyperlink popup state
boolean
required
Whether to show the welcome screen
Messages and Notifications
boolean
required
Whether the app is in a loading state
React.ReactNode
required
Current error message to display
{ message: string; closable?: boolean; duration?: number } | null
required
Toast notification configuration
Canvas State
Viewport
number
required
Horizontal scroll offset of the canvas
number
required
Vertical scroll offset of the canvas
Zoom
required
Zoom level configuration object with normalized value
number
required
Canvas width in pixels
number
required
Canvas height in pixels
number
required
Left offset of the canvas container
number
required
Top offset of the canvas container
boolean
required
Whether the user has scrolled outside the canvas bounds
View Settings
string
required
Background color of the canvas
boolean
required
Whether view-only mode is enabled (no editing)
boolean
required
Whether zen mode is enabled (minimal UI)
boolean
required
Whether grid is visible
number
required
Grid cell size in pixels
number
required
Grid step multiplier
boolean
required
Whether object snapping is enabled
readonly SnapLine[]
required
Current snap lines for alignment
{ x: number; y: number } | null
required
Offset for origin snapping
Theme
required
Current theme:
"light" or "dark"Frame Rendering
FrameRendering
required
Frame rendering configuration:
enabled: boolean- Whether frames are renderedname: boolean- Whether frame names are shownoutline: boolean- Whether frame outlines are shownclip: boolean- Whether content is clipped to frames
ExcalidrawFrameLikeElement | null
required
Frame element currently being highlighted
string | null
required
ID of the frame currently being edited
Element State
Selection
Readonly<{ [id: string]: true }>
required
Map of selected element IDs
{ [id: string]: true }
required
Previously selected element IDs
Readonly<{ [id: string]: true }>
required
Map of hovered element IDs
{ [groupId: string]: boolean }
required
Top-most selected groups (does not include nested groups)
GroupId | null
required
Group being edited when you drill down to its constituent element (e.g., when double-clicking a group element)
NonDeleted<ExcalidrawElement>[] | null
required
Elements to highlight
Element Manipulation
NonDeleted<ExcalidrawNonSelectionElement> | null
required
Newly created element being drawn (set on pointer down, updated during pointer move, used on pointer up)
NonDeletedExcalidrawElement | null
required
Element currently being resized (set on pointer down when selected and active tool is selection)
NonDeleted<ExcalidrawLinearElement> | null
required
Multi-point linear element created by clicking (not dragging). When set, the editor handles linear element creation logic
NonDeletedExcalidrawElement | null
required
Selection box element (decoupled from newElement, dragging selection only creates selectionElement)
boolean
required
Whether an element is currently being resized
boolean
required
Whether an element is currently being rotated
boolean
required
Whether selected elements are being dragged
Text Editing
NonDeletedExcalidrawElement | null
required
Text element currently being edited (set when creating new text or editing existing text)
Linear Elements
LinearElementEditor | null
required
Currently selected linear element with editing state
Binding
boolean
required
Whether element binding is enabled
NonDeleted<ExcalidrawBindableElement> | null
required
Element at the start of a binding operation
SuggestedBinding | null
required
Suggested binding during arrow creation:
element: NonDeleted<ExcalidrawBindableElement>midPoint?: GlobalPoint
BindMode
required
Current binding mode:
"inside" | "orbit" | "skip"Embeddables
ActiveEmbeddable | null
required
Currently active embeddable element:
element: NonDeletedExcalidrawElementstate: "hover" | "active"
Image Cropping
boolean
required
Whether image cropping mode is active
string | null
required
ID of the element being cropped
Locking
string | null
required
The locked element/group that’s active and shows unlock popup
{ [groupId: string]: true }
required
Temporary group IDs for locked multi-selections. Elements are unlocked together and groupId is removed
Tool State
ActiveTool & { lastActiveTool: ActiveTool | null; locked: boolean; fromSelection: boolean }
required
Current active tool configuration:
type: ToolTypeor"custom"customType: string | nulllastActiveTool- Previous tool to revert to (applies to eraser and hand)locked- Whether tool is lockedfromSelection- Whether tool is temporarily switched from selection tool
{ type: 'selection' | 'lasso'; initialized: boolean }
required
User’s preferred selection tool
boolean
required
Whether pen mode is active
boolean
required
Whether pen input has been detected
Current Drawing Properties
These properties represent the current tool settings that will be applied to newly created elements.string
required
Current stroke color for new elements
string
required
Current background color for new elements
FillStyle
required
Current fill style for new elements
number
required
Current stroke width for new elements
StrokeStyle
required
Current stroke style for new elements
number
required
Current roughness for new elements
number
required
Current opacity for new elements
FontFamilyValues
required
Current font family for new text elements
number
required
Current font size for new text elements
TextAlign
required
Current text alignment for new text elements
Arrowhead | null
required
Current start arrowhead for new arrows
Arrowhead | null
required
Current end arrowhead for new arrows
StrokeRoundness
required
Current roundness for new elements
'sharp' | 'round' | 'elbow'
required
Current arrow type for new arrows
FontFamilyValues | null
required
Font family currently being hovered in the font picker
Export Settings
boolean
required
Whether to include background when exporting
boolean
required
Whether to embed scene data when exporting
boolean
required
Whether to export using dark mode colors
number
required
Export scale multiplier
Pointer and Input State
PointerType
required
Last pointer type used:
"mouse" | "pen" | "touch"'up' | 'down'
required
Current cursor button state
File State
string | null
required
Name of the current file/scene
FileSystemHandle | null
required
File system handle for the current file
Collaboration
Map<SocketId, Collaborator>
required
Map of active collaborators by socket ID
UserToFollow | null
required
The user’s socket ID and username who is being followed on the canvas
Set<SocketId>
required
Set of socket IDs of users following the current user
Statistics
{ open: boolean; panels: number }
required
Statistics panel state:
open- Whether stats panel is openpanels- Bitmap of visible panels (use STATS_PANELS bit values)
Chart Settings
ChartType
required
Current chart type:
"bar" | "line"Search
SearchMatches | null
required
Current search matches, or null if no search is active:
focusedId: string | null- Currently focused matchmatches: readonly SearchMatch[]- Array of all matches
UI Preferences
boolean
required
User preference for whether the default sidebar should be docked. Note: This is only a preference and does not reflect actual docked state, as host apps can override this
boolean
required
Whether to cache rendering ignoring zoom level
Supporting Types
Zoom
NormalizedZoomValue
required
Normalized zoom value (branded number type)
Collaborator
CollaboratorPointer
Collaborator’s pointer position and configuration
'up' | 'down'
Collaborator’s button state
AppState['selectedElementIds']
Collaborator’s selected elements
string | null
Collaborator’s username
UserIdleState
Collaborator’s idle state
{ background: string; stroke: string }
Collaborator’s cursor colors
string
URL of collaborator’s avatar (defaults to username initials if not present)
string
User ID (used to filter duplicates when rendering avatars)
SocketId
Collaborator’s socket ID
boolean
Whether this is the current user
boolean
Whether collaborator is in a call
boolean
Whether collaborator is speaking
boolean
Whether collaborator is muted
CollaboratorPointer
number
required
X coordinate of pointer
number
required
Y coordinate of pointer
'pointer' | 'laser'
required
Tool type
boolean
default:"true"
Whether to render cursor and username (useful when only rendering laser trail)
string
Explicit laser color (defaults to collaborator’s cursor color)
SearchMatch
string
required
Element ID of the match
boolean
required
Whether this match is focused
MatchedLine[]
required
Array of matched line positions
UserToFollow
SocketId
required
Socket ID of the user being followed
string
required
Username of the user being followed