Actions: the general mechanism behind every state change

Chapter IV

Every visible edit in Excalidraw — delete, duplicate, flip, lock, change a color — is implemented as an Action object: a plain record with a name, a perform() function, an optional keyboard test, and an optional panel widget, declared once via register() and collected into a single array. ActionManager is the dispatcher that turns any trigger (keydown, panel click, context-menu item, command-palette pick, or a direct API call) into a lookup-by-name and a call to that action's perform(), then hands the returned ActionResult to App.syncActionResult, which commits elements and AppState through the same Scene/Store primitives you saw in updateScene. This module generalizes the one hard-coded 'draw a rectangle' path into the architecture behind essentially the whole editor.

From any trigger to a scene change: the Action system

actions/index.ts…kages/excalidraw/actions/index.ts

Every trigger site…ges/excalidraw/components/App.tsx

actions/register.ts — the shared actions array…es/excalidraw/actions/register.ts

ActionManager…ges/excalidraw/components/App.tsx

Action.perform()…kages/excalidraw/actions/types.ts

App.syncActionResult…ges/excalidraw/components/App.tsx

Figure I · Click a node to see what it does, where it lives in the code, and its labeled connections — the annotation opens beside it.

walkthrough

One concrete Action: actionFlipHorizontal

packages/excalidraw/actions/actionFlip.ts · lines 29–52

lines 29–33

name is the ActionName key ActionManager will store this under ('flipHorizontal' in the union defined in types.ts); label is an i18n key the UI resolves wherever this action is rendered as a menu item or shortcut-help row; icon and trackEvent feed that same UI/analytics regardless of what triggered the action. None of this is special to flipping — every registered action carries this same metadata shape.

lines 34–49

perform matches the ActionFn signature: (elements, appState, formData, app) in, an ActionResult out. It computes the flipped elements, hands the (unchanged) appState back alongside them, and sets captureUpdate to IMMEDIATELY — telling Store this edit should land on the undo stack right away, reusing the CaptureUpdateAction mechanism from the drawing trace.

line 51

keyTest is the shortcut binding itself, not a lookup into some separate keymap file: it is a plain boolean check on the raw key event. ActionManager runs every registered action's keyTest against each keydown and fires whichever one matches — the action defines its own shortcut inline.

29export const actionFlipHorizontal = register({30  name: "flipHorizontal",31  label: "labels.flipHorizontal",32  icon: flipHorizontal,33  trackEvent: { category: "element" },34  perform: (elements, appState, _, app) => {35    return {36      elements: updateFrameMembershipOfSelectedElements(37        flipSelectedElements(38          elements,39          app.scene.getNonDeletedElementsMap(),40          appState,41          "horizontal",42          app,43        ),44        appState,45        app,46      ),47      appState,48      captureUpdate: CaptureUpdateAction.IMMEDIATELY,49    };50  },51  keyTest: (event) => event.shiftKey && event.code === CODES.H,52});

step 1 of 3

walkthrough

executeAction: the one function every trigger funnels through

packages/excalidraw/actions/manager.tsx · lines 132–143

lines 132–136

source defaults to "api" — a test or a host app calling executeAction(actionDeleteSelected) directly needs to pass nothing extra. ContextMenu.tsx passes "contextMenu", CommandPalette.tsx passes "commandPalette": same method, only this one string differs, and it's used purely for analytics tagging (see trackAction below), never to change what runs.

lines 137–138

It re-reads elements and appState fresh through the getters App handed ActionManager at construction — the exact same getters handleKeyDown uses for keyboard shortcuts — so an action never operates on stale state, regardless of how long ago the manager was built.

line 142

This is the whole mechanism in one line: call action.perform(...) and hand its return value straight to this.updater. ActionManager never inspects what changed — it doesn't know or care whether flipHorizontal, deleteSelectedElements, or changeStrokeColor just ran. That's what makes it a general dispatcher instead of a pile of if-else branches per command.

132  executeAction<T extends Action>(133    action: T,134    source: ActionSource = "api",135    value: Parameters<T["perform"]>[2] = null,136  ) {137    const elements = this.getElementsIncludingDeleted();138    const appState = this.getAppState();139140    trackAction(action, source, appState, elements, this.app, value);141142    this.updater(action.perform(elements, appState, value, this.app));143  }

step 1 of 3

Connects

The updater is App.syncActionResult, not literally updateScene — ActionManager was constructed as new ActionManager(this.syncActionResult, ...) — so this.updater inside executeAction is App's syncActionResult method, not the updateScene method from the drawing trace. But look at what syncActionResult does: this.store.scheduleAction(actionResult.captureUpdate), then this.scene.replaceAllElements(actionResult.elements), then a setState merging actionResult.appState. Those are the identical Scene/Store primitives updateScene used to commit your rectangle. Actions don't reuse the updateScene function itself — they reuse its commit machinery through a sibling method built from the same parts.

packages/excalidraw/components/App.tsx · syncActionResult :863–868packages/excalidraw/components/App.tsx · scheduleAction :2821–2821packages/excalidraw/components/App.tsx · replaceAllElements :2827–2827

285    return {286      elements: nextElements,287      appState: {288        ...nextAppState,289        activeTool: updateActiveTool(appState, {290          type: app.state.preferredSelectionTool.type,291        }),292        multiElement: null,293        newElement: null,294        activeEmbeddable: null,295        selectedLinearElement: null,296      },297      captureUpdate: isSomeElementSelected(298        getNonDeletedElements(elements),299        appState,300      )301        ? CaptureUpdateAction.IMMEDIATELY302        : CaptureUpdateAction.EVENTUALLY,303    };

packages/excalidraw/actions/actionDeleteSelected.tsx · lines 285–303

Figure II · Deleting elements is never just an elements edit here: the same return statement resets appState.activeTool back to the selection tool and clears multiElement/newElement/activeEmbeddable/selectedLinearElement — UI state that has nothing to do with the elements array. AppState is the other half of what updateScene-style commits carry, and an Action's perform() is the main place both halves get edited together as one atomic ActionResult. captureUpdate itself is even computed dynamically here (IMMEDIATELY only if something is still selected), showing an action deciding its own undo granularity rather than App deciding it uniformly.

16  it("frame only", async () => {17    const f1 = API.createElement({18      type: "frame",19    });2021    const r1 = API.createElement({22      type: "rectangle",23      frameId: f1.id,24    });2526    API.setElements([f1, r1]);2728    API.setSelectedElements([f1]);2930    act(() => {31      h.app.actionManager.executeAction(actionDeleteSelected);32    });3334    assertElements(h.elements, [35      { id: f1.id, isDeleted: true },36      { id: r1.id, isDeleted: false, selected: true },37    ]);38  });

packages/excalidraw/actions/actionDeleteSelected.test.tsx · lines 16–38

Figure III · This test never simulates a keypress or a click — it calls h.app.actionManager.executeAction(actionDeleteSelected) directly, the exact same 'api'-source path a host application's imperative API would use. The assertion afterward reads h.elements, the live Scene contents from the drawing-trace module: proof that perform()'s ActionResult really did travel ActionManager → syncActionResult → Scene, with no UI involved at all.

What you can do now

You can now find the exact code behind any editor command: pick its ActionName (e.g. "flipHorizontal", "deleteSelectedElements") and read straight to the register({...}) call that declares it. You can trace a keyboard shortcut, a toolbar/panel click, a context-menu item, and a command-palette entry back to one shared executeAction/handleKeyDown call instead of treating each as separately-wired UI. And you can add a genuinely new editor command yourself — write an Action object with perform (and optionally keyTest/PanelComponent), export it from actions/index.ts — and get undo/redo, a keyboard shortcut, and menu rendering for free from machinery you've now read end to end.

packages/excalidraw/actions/manager.tsx · executeAction :132–143packages/excalidraw/actions/register.ts · register :5–15

checkpoint

Check your understanding

Answered in place — nothing is graded, everything is explained. 0 / 3 passed

Where is the actionFlipHorizontal command actually declared as an Action object (name, perform, keyTest)?

In ActionManager.executeAction, once action.perform(...) returns an ActionResult, what happens to it?

What is an Action's keyTest function used for?