AppState

Type definition for Excalidraw’s application state

AppState

The complete application state interface for Excalidraw. This contains all UI state, canvas state, tool state, and user preferences.

UI State

Context Menu

contextMenu · { items: ContextMenuItems; top: number; left: number } | null · required

Current context menu state including items and position, or null if no context menu is shown

Dialogs and Modals

openDialog · 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 }

openMenu · 'canvas' | null · required

Currently open menu

openPopup · OpenPopup · required

Currently open popup. Can be:

• "canvasBackground"
• "elementBackground"
• "elementStroke"
• "fontFamily"
• "compactTextProperties"
• "compactStrokeStyles"
• "compactOtherProperties"
• "compactArrowProperties"
• null

openSidebar · { name: SidebarName; tab?: SidebarTabName } | null · required

Currently open sidebar with optional tab selection

pasteDialog · PasteDialog · required

Paste dialog state:

• { shown: false; data: null }
• { shown: true; data: Spreadsheet }

showHyperlinkPopup · false | 'info' | 'editor' · required

Hyperlink popup state

showWelcomeScreen · boolean · required

Whether to show the welcome screen

Messages and Notifications

isLoading · boolean · required

Whether the app is in a loading state

errorMessage · React.ReactNode · required

Current error message to display

toast · { message: string; closable?: boolean; duration?: number } | null · required

Toast notification configuration

Canvas State

Viewport

scrollX · number · required

Horizontal scroll offset of the canvas

scrollY · number · required

Vertical scroll offset of the canvas

zoom · Zoom · required

Zoom level configuration object with normalized value

width · number · required

Canvas width in pixels

height · number · required

Canvas height in pixels

offsetLeft · number · required

Left offset of the canvas container

offsetTop · number · required

Top offset of the canvas container

scrolledOutside · boolean · required

Whether the user has scrolled outside the canvas bounds

View Settings

viewBackgroundColor · string · required

Background color of the canvas

viewModeEnabled · boolean · required

Whether view-only mode is enabled (no editing)

zenModeEnabled · boolean · required

Whether zen mode is enabled (minimal UI)

gridModeEnabled · boolean · required

Whether grid is visible

gridSize · number · required

Grid cell size in pixels

gridStep · number · required

Grid step multiplier

objectsSnapModeEnabled · boolean · required

Whether object snapping is enabled

snapLines · readonly SnapLine[] · required

Current snap lines for alignment

originSnapOffset · { x: number; y: number } | null · required

Offset for origin snapping

theme · Theme · required

Current theme: "light" or "dark"

Frame Rendering

frameRendering · FrameRendering · required

Frame rendering configuration:

• enabled: boolean - Whether frames are rendered
• name: boolean - Whether frame names are shown
• outline: boolean - Whether frame outlines are shown
• clip: boolean - Whether content is clipped to frames

frameToHighlight · ExcalidrawFrameLikeElement | null · required

Frame element currently being highlighted

editingFrame · string | null · required

ID of the frame currently being edited

Element State

Selection

selectedElementIds · Readonly<{ [id: string]: true }> · required

Map of selected element IDs

previousSelectedElementIds · { [id: string]: true } · required

Previously selected element IDs

hoveredElementIds · Readonly<{ [id: string]: true }> · required

Map of hovered element IDs

selectedGroupIds · { [groupId: string]: boolean } · required

Top-most selected groups (does not include nested groups)

editingGroupId · GroupId | null · required

Group being edited when you drill down to its constituent element (e.g., when double-clicking a group element)

elementsToHighlight · NonDeleted<ExcalidrawElement>[] | null · required

Elements to highlight

Element Manipulation

newElement · NonDeleted<ExcalidrawNonSelectionElement> | null · required

Newly created element being drawn (set on pointer down, updated during pointer move, used on pointer up)

resizingElement · NonDeletedExcalidrawElement | null · required

Element currently being resized (set on pointer down when selected and active tool is selection)

multiElement · NonDeleted<ExcalidrawLinearElement> | null · required

Multi-point linear element created by clicking (not dragging). When set, the editor handles linear element creation logic

selectionElement · NonDeletedExcalidrawElement | null · required

Selection box element (decoupled from newElement, dragging selection only creates selectionElement)

isResizing · boolean · required

Whether an element is currently being resized

isRotating · boolean · required

Whether an element is currently being rotated

selectedElementsAreBeingDragged · boolean · required

Whether selected elements are being dragged

Text Editing

editingTextElement · NonDeletedExcalidrawElement | null · required

Text element currently being edited (set when creating new text or editing existing text)

Linear Elements

selectedLinearElement · LinearElementEditor | null · required

Currently selected linear element with editing state

Binding

isBindingEnabled · boolean · required

Whether element binding is enabled

startBoundElement · NonDeleted<ExcalidrawBindableElement> | null · required

Element at the start of a binding operation

suggestedBinding · SuggestedBinding | null · required

Suggested binding during arrow creation:

• element: NonDeleted<ExcalidrawBindableElement>
• midPoint?: GlobalPoint

bindMode · BindMode · required

Current binding mode: "inside" | "orbit" | "skip"

Embeddables

activeEmbeddable · ActiveEmbeddable | null · required

Currently active embeddable element:

• element: NonDeletedExcalidrawElement
• state: "hover" | "active"

Image Cropping

isCropping · boolean · required

Whether image cropping mode is active

croppingElementId · string | null · required

ID of the element being cropped

Locking

activeLockedId · string | null · required

The locked element/group that’s active and shows unlock popup

lockedMultiSelections · { [groupId: string]: true } · required

Temporary group IDs for locked multi-selections. Elements are unlocked together and groupId is removed

Tool State

activeTool · ActiveTool & { lastActiveTool: ActiveTool | null; locked: boolean; fromSelection: boolean } · required

Current active tool configuration:

• type: ToolType or "custom"
• customType: string | null
• lastActiveTool - Previous tool to revert to (applies to eraser and hand)
• locked - Whether tool is locked
• fromSelection - Whether tool is temporarily switched from selection tool

preferredSelectionTool · { type: 'selection' | 'lasso'; initialized: boolean } · required

User’s preferred selection tool

penMode · boolean · required

Whether pen mode is active

penDetected · 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.

currentItemStrokeColor · string · required

Current stroke color for new elements

currentItemBackgroundColor · string · required

Current background color for new elements

currentItemFillStyle · FillStyle · required

Current fill style for new elements

currentItemStrokeWidth · number · required

Current stroke width for new elements

currentItemStrokeStyle · StrokeStyle · required

Current stroke style for new elements

currentItemRoughness · number · required

Current roughness for new elements

currentItemOpacity · number · required

Current opacity for new elements

currentItemFontFamily · FontFamilyValues · required

Current font family for new text elements

currentItemFontSize · number · required

Current font size for new text elements

currentItemTextAlign · TextAlign · required

Current text alignment for new text elements

currentItemStartArrowhead · Arrowhead | null · required

Current start arrowhead for new arrows

currentItemEndArrowhead · Arrowhead | null · required

Current end arrowhead for new arrows

currentItemRoundness · StrokeRoundness · required

Current roundness for new elements

currentItemArrowType · 'sharp' | 'round' | 'elbow' · required

Current arrow type for new arrows

currentHoveredFontFamily · FontFamilyValues | null · required

Font family currently being hovered in the font picker

Export Settings

exportBackground · boolean · required

Whether to include background when exporting

exportEmbedScene · boolean · required

Whether to embed scene data when exporting

exportWithDarkMode · boolean · required

Whether to export using dark mode colors

exportScale · number · required

Export scale multiplier

Pointer and Input State

lastPointerDownWith · PointerType · required

Last pointer type used: "mouse" | "pen" | "touch"

cursorButton · 'up' | 'down' · required

Current cursor button state

File State

name · string | null · required

Name of the current file/scene

fileHandle · FileSystemHandle | null · required

File system handle for the current file

Collaboration

collaborators · Map<SocketId, Collaborator> · required

Map of active collaborators by socket ID

userToFollow · UserToFollow | null · required

The user’s socket ID and username who is being followed on the canvas

followedBy · Set<SocketId> · required

Set of socket IDs of users following the current user

Statistics

stats · { open: boolean; panels: number } · required

Statistics panel state:

• open - Whether stats panel is open
• panels - Bitmap of visible panels (use STATS_PANELS bit values)

Chart Settings

currentChartType · ChartType · required

Current chart type: "bar" | "line"

Search

searchMatches · SearchMatches | null · required

Current search matches, or null if no search is active:

• focusedId: string | null - Currently focused match
• matches: readonly SearchMatch[] - Array of all matches

UI Preferences

defaultSidebarDockedPreference · 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

shouldCacheIgnoreZoom · boolean · required

Whether to cache rendering ignoring zoom level

Supporting Types

Zoom

value · NormalizedZoomValue · required

Normalized zoom value (branded number type)

Collaborator

pointer · CollaboratorPointer

Collaborator’s pointer position and configuration

button · 'up' | 'down'

Collaborator’s button state

selectedElementIds · AppState['selectedElementIds']

Collaborator’s selected elements

username · string | null

Collaborator’s username

userState · UserIdleState

Collaborator’s idle state

color · { background: string; stroke: string }

Collaborator’s cursor colors

avatarUrl · string

URL of collaborator’s avatar (defaults to username initials if not present)

id · string

User ID (used to filter duplicates when rendering avatars)

socketId · SocketId

Collaborator’s socket ID

isCurrentUser · boolean

Whether this is the current user

isInCall · boolean

Whether collaborator is in a call

isSpeaking · boolean

Whether collaborator is speaking

isMuted · boolean

Whether collaborator is muted

CollaboratorPointer

x · number · required

X coordinate of pointer

y · number · required

Y coordinate of pointer

tool · 'pointer' | 'laser' · required

Tool type

renderCursor · boolean · default: "true"

Whether to render cursor and username (useful when only rendering laser trail)

laserColor · string

Explicit laser color (defaults to collaborator’s cursor color)

SearchMatch

id · string · required

Element ID of the match

focus · boolean · required

Whether this match is focused

matchedLines · MatchedLine[] · required

Array of matched line positions

UserToFollow

socketId · SocketId · required

Socket ID of the user being followed

username · string · required

Username of the user being followed

Derived Types

UIAppState

AppState without internal pointer/cursor state:

type UIAppState = Omit<AppState, "startBoundElement" | "cursorButton" | "scrollX" | "scrollY">

StaticCanvasAppState

Minimal state for rendering static canvas.

InteractiveCanvasAppState

State for rendering interactive canvas with selection and collaboration features.