/build-gpui-apps

Actions & Keybindings

Contents: Overview · Quick Start · Key Formats · Menu Bar Shortcuts · Action Naming · Context-Aware Bindings · Best Practices

Overview

Actions provide declarative keyboard-driven UI interactions in GPUI.

Key Concepts:

• Define actions with actions! macro or #[derive(Action)]
• Bind keys with cx.bind_keys()
• Handle with .on_action() on elements
• Context-aware via key_context()

Quick Start

Simple Actions

use gpui_kit::actions;

actions!(editor, [MoveUp, MoveDown, Save, Quit]);

const CONTEXT: &str = "Editor";

pub fn init(cx: &mut App) {
    cx.bind_keys([
        KeyBinding::new("up", MoveUp, Some(CONTEXT)),
        KeyBinding::new("down", MoveDown, Some(CONTEXT)),
        KeyBinding::new("cmd-s", Save, Some(CONTEXT)),
        KeyBinding::new("cmd-q", Quit, Some(CONTEXT)),
    ]);
}

impl Render for Editor {
    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .key_context(CONTEXT)
            .on_action(cx.listener(Self::move_up))
            .on_action(cx.listener(Self::move_down))
            .on_action(cx.listener(Self::save))
    }
}

impl Editor {
    fn move_up(&mut self, _: &MoveUp, cx: &mut Context<Self>) {
        // Handle move up
        cx.notify();
    }

    fn move_down(&mut self, _: &MoveDown, cx: &mut Context<Self>) {
        cx.notify();
    }

    fn save(&mut self, _: &Save, cx: &mut Context<Self>) {
        // Save logic
        cx.notify();
    }
}

Actions with Parameters

#[derive(Clone, PartialEq, Action, Deserialize)]
#[action(namespace = editor)]
pub struct InsertText {
    pub text: String,
}

#[derive(Action, Clone, PartialEq, Eq, Deserialize)]
#[action(namespace = editor, no_json)]
pub struct Digit(pub u8);

cx.bind_keys([
    KeyBinding::new("0", Digit(0), Some(CONTEXT)),
    KeyBinding::new("1", Digit(1), Some(CONTEXT)),
    // ...
]);

impl Editor {
    fn on_digit(&mut self, action: &Digit, cx: &mut Context<Self>) {
        self.insert_digit(action.0, cx);
    }
}

Key Formats

// Modifiers
"cmd-s"         // Command (macOS) / Ctrl (Windows/Linux)
"ctrl-c"        // Control
"alt-f"         // Alt
"shift-tab"     // Shift
"cmd-ctrl-f"    // Multiple modifiers

// Keys
"a-z", "0-9"    // Letters and numbers
"f1-f12"        // Function keys
"up", "down", "left", "right"
"enter", "escape", "space", "tab"
"backspace", "delete"
"-", "=", "[", "]", etc.  // Special characters

Menu Bar Shortcuts

cx.set_menus reads the keymap at the moment it is called and bakes each item's shortcut into the native menu. A key bound afterwards never appears next to its menu item, and the item does not react to that key. There is no event to hook: bind first, then build the menus, and rebuild them when the keymap changes.

pub fn init(cx: &mut App) {
    // 1. Bindings first — the menu items copy their shortcuts from these.
    cx.bind_keys([
        KeyBinding::new("cmd-n", NewChat, None),
        KeyBinding::new("cmd-,", OpenSettings, None),
        KeyBinding::new("cmd-q", Quit, None),
    ]);

    // 2. Then the menu bar.
    cx.set_menus(vec![Menu {
        name: "File".into(),
        items: vec![
            MenuItem::action("New Chat", NewChat),
            MenuItem::action("Settings…", OpenSettings),
            MenuItem::separator(),
            MenuItem::action("Quit", Quit),
        ],
    }]);
}

Call cx.set_menus again after anything that changes bindings or labels: a user keymap file loaded later, a locale switch that renames the items. Undo, Redo, Cut, Copy, Paste need no on_action of your own — give the item an OsAction and the platform forwards it to the focused text control.

Action Naming

Prefer verb-noun pattern:

actions!([
    OpenFile,      // ✅ Good
    CloseWindow,   // ✅ Good
    ToggleSidebar, // ✅ Good
    Save,          // ✅ Good (common exception)
]);

Context-Aware Bindings

const EDITOR_CONTEXT: &str = "Editor";
const MODAL_CONTEXT: &str = "Modal";

// Same key, different contexts
cx.bind_keys([
    KeyBinding::new("escape", CloseModal, Some(MODAL_CONTEXT)),
    KeyBinding::new("escape", ClearSelection, Some(EDITOR_CONTEXT)),
]);

// Set context on element
div()
    .key_context(EDITOR_CONTEXT)
    .child(editor_content)

Best Practices

✅ Use Contexts

// ✅ Good: Context-aware
div()
    .key_context("MyComponent")
    .on_action(cx.listener(Self::handle))

✅ Name Actions Clearly

// ✅ Good: Clear intent
actions!([
    SaveDocument,
    CloseTab,
    TogglePreview,
]);

✅ Handle with Listeners

// ✅ Good: Proper handler naming
impl MyComponent {
    fn on_action_save(&mut self, _: &Save, cx: &mut Context<Self>) {
        // Handle save
        cx.notify();
    }
}

div().on_action(cx.listener(Self::on_action_save))

Merged from GPUI Kit skill. Apache-2.0. Imported 2026-09-28; local links and version-sensitive guidance adapted. The current documentation and locked source take precedence over example signatures.