Interacting with Your UI: Actions and Event Handling

In previous chapters, you’ve mastered setting up your GPUI environment, creating windows, and displaying static content. While seeing “Hello, GPUI!” is a great start, a truly useful application needs to respond to user input. This chapter is your gateway to making your GPUI applications interactive.

We’ll dive into GPUI’s powerful Actions and Event Handling system. You’ll learn how raw user input, like keyboard presses and mouse clicks, is transformed into structured “actions” that your application understands. By the end, you’ll be able to define custom actions, dispatch them from your UI elements, and write handlers to bring your GPUI applications to life.

Ready to make your UI not just look good, but also do something? Let’s get started!

The GPUI Event Loop: The Foundation of Interaction

Every interactive application relies on an event-driven model. This means the application isn’t constantly performing tasks; instead, it waits for “events” to occur and then reacts to them. GPUI builds upon this fundamental concept with its own sophisticated event loop and an abstraction layer called “Actions.”

How Events Drive Your Application

Imagine your GPUI application as a patient listener, always attuned to its environment. This continuous cycle of waiting for input, processing it, and updating the display is the event loop.

User Input: A user presses a key, clicks a mouse button, or scrolls.
Operating System Event: The operating system (macOS or Linux in our case) detects this input and sends a low-level event to your GPUI application.
GPUI Runtime: GPUI’s internal runtime captures these raw events.
Action Translation: If an event matches a predefined rule (like a keybinding), GPUI translates it into a higher-level, application-specific Action.

This process is crucial because it separates the low-level details of input from the high-level logic of your application. Your UI components don’t need to care how a SaveFile action was triggered (e.g., Cmd+S, a menu click, or an API call); they just need to know what SaveFile means.

Actions: Your Application’s Commands

In GPUI, an Action is a structured, named command that represents a specific operation within your application. Think of actions as the verbs of your UI—they describe what the user or application wants to do.

Why Actions are Essential

Actions are central to GPUI’s architecture for several compelling reasons:

Decoupling UI from Logic: UI elements simply dispatch actions. They don’t need to know the intricate details of how those actions are handled. This makes your UI code cleaner and easier to maintain.
Enhanced Testability: You can trigger actions directly in tests, completely bypassing the UI, to verify your application’s core logic.
Flexibility and Extensibility: New features can often be added by defining new actions and corresponding handlers without modifying existing UI components.
Configurable Input: GPUI’s robust keybinding system allows users to customize keyboard shortcuts, mapping various input combinations to the same underlying action.

Defining Actions with the `actions!` Macro

GPUI provides a convenient actions! macro to define your custom actions. This macro generates the necessary boilerplate, including the struct definition and the implementation of the gpui::Action trait (which requires a unique name() for the action).

// A conceptual example of actions! macro usage
actions!(my_app_crate, [
    // ActionName,
    // AnotherActionNameWithData { value: usize },
]);

⚡ Quick Note: The actions! macro in GPUI (as of 2026-05-24) automatically derives several traits like Debug, Clone, PartialEq, Eq, and Hash for your actions, which are necessary for GPUI’s internal handling of actions and keybindings. You typically don’t need to worry about these derivations when using the macro.

Handlers: Responding to Actions

An action by itself doesn’t do anything; it’s merely a declaration. For an action to have an effect, it needs an action handler. An action handler is a function or closure that GPUI invokes when a specific action is dispatched.

Handlers are where your application’s logic resides. They receive the action (and any data it carries) and the current WindowContext (or AppContext for global handlers), allowing them to update the application state, modify views, or trigger other operations.

The lifecycle of an action looks something like this:

flowchart TD A[User Input] --> B{GPUI Runtime} B -->|Raw Event| C[Input Bindings] C -->|Matches Binding| D[Action Dispatched] D -->|Finds Handler| E[Action Handler] E -->|Updates State| F[View Notified] F -->|Triggers| G[UI Re-render]

⚡ Real-world insight: The Zed editor, built with GPUI, uses this action system extensively. Every command you execute, whether through a keybinding, a menu item, or the command palette, dispatches a specific action. This unified approach makes Zed incredibly flexible and extensible. Developers can easily add new commands by defining actions and handlers.

Dispatching Actions: Making Things Happen

There are two primary ways to dispatch an action in GPUI:

Programmatically from UI Events: This is typical for interactive elements like buttons. When a user clicks a button, its on_mouse_down handler will call cx.dispatch_action().
Via Global Keybindings: You can register keyboard shortcuts that, when pressed, automatically dispatch a specific action.

`cx.dispatch_action()`

This is the core method for triggering an action. You call it within a WindowContext (or AppContext) and pass an instance of your action struct.

// Example: Dispatching an action
cx.dispatch_action(MyCustomAction { value: 10 });

Registering Handlers: `defer_action` and `bind_keys`

GPUI provides mechanisms to register handlers:

cx.defer_action() (View-specific Handlers):
- This method registers an action handler that is tied to the lifecycle of a specific View instance.
- The handler will only execute if the view it’s registered on (or one of its children) currently has keyboard focus.
- It’s ideal for actions that are relevant only when a particular UI component is active.
- The returned ActionRegistration object keeps the handler alive as long as the view is alive.
cx.bind_keys() (Global Keybindings):
- This method, typically called during application initialization (App::new().run), registers a global keybinding.
- When the specified key combination is pressed, the associated action is dispatched, regardless of which view has focus.
- The handler closure you provide to bind_keys usually just calls cx.dispatch_action() to trigger the relevant action.

Updating the UI: The Critical `cx.notify()`

After an action handler modifies your view’s state (e.g., incrementing a counter), GPUI needs to know that the UI might look different. This is where cx.notify() comes in.

🧠 Important: Whenever you change state within a View that should trigger a re-render of that view, you must call cx.notify() on the WindowContext. If you forget this, your state will update internally, but the visual UI will remain stale, leading to a confusing user experience.

cx.notify() tells GPUI’s rendering engine, “Hey, something changed in this view, please re-render it soon!” GPUI then intelligently schedules a re-render pass, ensuring efficiency.

Step-by-Step Implementation: Building an Interactive Counter

Let’s build on our basic application structure to create a simple counter with interactive buttons and keyboard shortcuts.

1. Project Setup and Dependencies

First, ensure you have a stable Rust toolchain. If you haven’t already, create a new Rust project:

cargo new gpui_actions_example --bin
cd gpui_actions_example

Now, open Cargo.toml and add GPUI as a dependency. As of 2026-05-24, we’re targeting the main branch of the zed-industries/zed repository for the latest GPUI features.

# Cargo.toml
[dependencies]
gpui = { git = "https://github.com/zed-industries/zed", branch = "main" }

2. Initial `src/main.rs` Structure

Open src/main.rs and set up the basic GPUI application shell. This will look familiar from previous chapters.

// src/main.rs
use gpui::{
    actions, App, AnyElement, AnyView, Bounds, Context, Element, Global,
    Model, Point, Render, Size, View, VisualContext, WeakView, WindowContext,
    WindowHandle, WindowOptions, WindowBounds, IntoElement,
    div, MouseButton,
};

// 1. Define our custom actions
actions!(gpui_actions_example, [
    IncrementCounter,
    DecrementCounter,
]);

// 2. Define our interactive view
struct CounterView {
    count: usize,
    // This field will hold the registration for our view-specific action handlers.
    // We'll initialize it in the `new_view` closure.
    _action_registration: gpui::ActionRegistration,
}

// 3. Implement the Render trait for our view
impl Render for CounterView {
    fn render(&mut self, _cx: &mut WindowContext) -> AnyElement {
        // Placeholder for now, we'll fill this in.
        div().child("Loading Counter...").into_any_element()
    }
}

// 4. Main application setup
fn main() {
    App::new().run(|cx: &mut Context| {
        // We'll add global keybindings here shortly.

        cx.open_window(
            WindowOptions {
                bounds: WindowBounds::Fixed(Bounds::new(
                    Point::new(0.0, 0.0),
                    Size::new(400.0, 200.0),
                )),
                titlebar: None, // No native title bar
                center: true, // Center the window on the screen
                focus: true, // Focus the window on creation
            },
            |cx| {
                // Create and return our CounterView
                let view = cx.new_view(|cx| {
                    CounterView {
                        count: 0,
                        // 5. Register the action handler for IncrementCounter
                        _action_registration: cx.defer_action(|this: &mut CounterView, _action: &IncrementCounter, cx| {
                            this.count += 1;
                            eprintln!("Count incremented to: {}", this.count);
                            cx.notify(); // Crucial: tell GPUI to re-render
                        }),
                    }
                });
                view
            },
        );
    });
}

Explanation of new parts:

actions!(gpui_actions_example, [IncrementCounter, DecrementCounter,]);: We define two empty structs, IncrementCounter and DecrementCounter, which will serve as our actions. The actions! macro handles all the Action trait implementations.
struct CounterView { count: usize, _action_registration: gpui::ActionRegistration, }: Our view struct will hold the count state. The _action_registration field is important: it’s where we store the result of cx.defer_action, ensuring our handler remains active for the lifetime of the CounterView.
cx.defer_action(...): Inside cx.new_view, we immediately register a handler for IncrementCounter.
- The closure receives this: &mut CounterView (mutable access to our view), _action: &IncrementCounter (the dispatched action), and cx: &mut WindowContext.
- this.count += 1;: We update the view’s internal state.
- cx.notify();: This is vital! It tells GPUI that CounterView’s state has changed and it needs to be re-rendered to reflect the new count.

3. Implement the View to Dispatch Actions

Now, let’s update the render method of CounterView to display the count and include an “Increment” button that dispatches our IncrementCounter action.

// src/main.rs (continuation)

// ... (previous code before impl Render for CounterView)

impl Render for CounterView {
    fn render(&mut self, cx: &mut WindowContext) -> AnyElement {
        div()
            .flex_col() // Arrange children vertically
            .justify_center() // Center children vertically
            .items_center() // Center children horizontally
            .size_full() // Take up all available space
            .child(
                div()
                    .text_xl() // Extra large text
                    .child(format!("Count: {}", self.count)), // Display current count
            )
            .child(
                div()
                    .mt_4() // Margin top 4 units
                    .py_2() // Padding Y axis 2 units
                    .px_4() // Padding X axis 4 units
                    .rounded_md() // Rounded corners
                    .bg_blue_500() // Blue background
                    .text_white() // White text
                    .cursor_pointer() // Indicate it's clickable
                    .on_mouse_down(MouseButton::Left, |_, cx| {
                        // When the button is clicked, dispatch the action!
                        cx.dispatch_action(IncrementCounter);
                    })
                    .child("Increment"),
            )
            .into_any_element()
    }
}

// ... (main function and other imports)

Explanation of new parts:

div().flex_col().justify_center().items_center().size_full(): These are GPUI’s element builders and styling macros (inspired by Tailwind CSS). They create a full-size container that centers its child elements.
div().text_xl().child(format!("Count: {}", self.count)): This div displays the current value of self.count with extra large text.
div().mt_4()...child("Increment"): This is our button element.
- on_mouse_down(MouseButton::Left, |_, cx| { ... }): This event handler listens for a left mouse button click on this specific div element.
- cx.dispatch_action(IncrementCounter);: Inside the click handler, we instruct GPUI to dispatch an IncrementCounter action. GPUI’s event loop will then find the appropriate handler (which we registered with defer_action in main) and execute it.

Now, if you run cargo run, you should see a window with “Count: 0” and an “Increment” button. Clicking the button will increment the count, and you’ll see the eprintln! output in your terminal, confirming the action fired and cx.notify() updated the UI.

4. Binding a Keyboard Shortcut

Let’s make our counter even more accessible by adding a global keyboard shortcut to increment the count. We’ll add this to our main function.

// src/main.rs (continuation)

// ... (previous code before fn main)

fn main() {
    App::new().run(|cx: &mut Context| {
        // Register a global keybinding for IncrementCounter
        cx.bind_keys([
            "cmd-alt-i",  // macOS: Command + Alt + I
            "ctrl-alt-i", // Linux: Control + Alt + I
        ], IncrementCounter, |_, cx| {
            // This closure is executed when the keybinding is pressed.
            // It dispatches the action globally.
            cx.dispatch_action(IncrementCounter);
        });

        cx.open_window(
            WindowOptions {
                bounds: WindowBounds::Fixed(Bounds::new(
                    Point::new(0.0, 0.0),
                    Size::new(400.0, 200.0),
                )),
                titlebar: None,
                center: true,
                focus: true,
            },
            |cx| {
                let view = cx.new_view(|cx| {
                    CounterView {
                        count: 0,
                        // Action handler for this view instance, responds to IncrementCounter
                        _action_registration: cx.defer_action(|this: &mut CounterView, _action: &IncrementCounter, cx| {
                            this.count += 1;
                            eprintln!("Count incremented to: {}", this.count);
                            cx.notify();
                        }),
                    }
                });
                view
            },
        );
    });
}

Explanation of new parts:

cx.bind_keys([...], IncrementCounter, |_, cx| { ... });: This function registers a global keybinding that will dispatch the IncrementCounter action.
- ["cmd-alt-i", "ctrl-alt-i"]: An array of key combinations. GPUI intelligently handles platform differences (cmd for macOS, ctrl for Linux).
- IncrementCounter: The action that this keybinding will dispatch.
- |_, cx| { cx.dispatch_action(IncrementCounter); }: The closure that gets executed when the keybinding is pressed. It simply dispatches the IncrementCounter action, which is then handled by our defer_action handler within CounterView. This means both the button click and the keyboard shortcut trigger the same underlying action, leading to consistent behavior.

Run cargo run again, and now you can increment the counter by clicking the button or by pressing Cmd+Alt+I (macOS) or Ctrl+Alt+I (Linux).

Mini-Challenge: Decrementing the Counter

You’ve successfully implemented incrementing the counter using both a button and a keyboard shortcut. Now, it’s your turn to add the ability to decrement it.

Challenge:

Add a “Decrement” Button: Modify the render method of CounterView to include a second button labeled “Decrement.”
Dispatch DecrementCounter: Configure the on_mouse_down handler for this new button to dispatch the DecrementCounter action.
Register DecrementCounter Handler: Within the cx.new_view closure (where you created CounterView), register a new cx.defer_action handler specifically for the DecrementCounter action. This handler should decrease self.count by 1. Remember to call cx.notify()!
(Optional) Add a Keyboard Shortcut: In your main function, add a global keybinding (e.g., Cmd/Ctrl+Alt+D) that dispatches the DecrementCounter action.

Hint: The pattern for DecrementCounter will be nearly identical to IncrementCounter. You might need to adjust the layout slightly (e.g., using flex_row for buttons instead of flex_col or adding more divs for spacing).

What to observe/learn: This challenge will solidify your understanding of defining actions, associating them with UI elements, registering view-specific handlers, and using global keybindings. You’ll see how GPUI’s action system enables modular and consistent interaction patterns.

Common Pitfalls & Troubleshooting

Working with an actively developing framework like GPUI can have its quirks. Here are some common issues and how to approach them:

UI Not Updating After State Change (cx.notify() is Missing):
- ⚠️ What can go wrong: This is the most frequent culprit for a seemingly unresponsive UI. Your action handler might successfully update self.count, but if you forget cx.notify(), GPUI won’t know to redraw the view.
- Troubleshooting: Always double-check that cx.notify() is called within any action handler or function that modifies a view’s state and expects a visual update.
Action Handler Not Firing:
- Is the view focused? Remember that cx.defer_action handlers are tied to view focus. If your CounterView isn’t the active or focused element (e.g., another window is active, or a child element has taken focus), its deferred action handler won’t run. Global cx.bind_keys handlers, however, will always fire.
- Is the action name correct? While the actions! macro helps, ensure the action type you’re dispatching (IncrementCounter) precisely matches the type you registered the handler for.
- Keybinding Conflicts: If you have multiple cx.bind_keys registrations for the exact same key combination, only one will typically be processed.
Unstable APIs and Frequent Breaking Changes:
- ⚠️ What can go wrong: GPUI is in active development, meaning its APIs can and do change frequently. Code that compiles and runs today from the main branch might not compile tomorrow.
- Troubleshooting:
  - Consult the Source Code: The absolute best and most up-to-date documentation for GPUI is the source code itself. Specifically, examine the zed-industries/zed repository’s crates/gpui directory. Look at README.md, lib.rs, and the examples within the Zed editor’s source for how things are currently done.
  - Review Recent Commits: Check the commit history for crates/gpui for recent API changes or refactorings that might affect your code.
  - Community: Engage with the Zed community if you encounter persistent issues.

Summary

You’ve made significant progress in making your GPUI applications interactive! Understanding actions and event handling is fundamental to building dynamic user interfaces.

Here are the key takeaways from this chapter:

Event-Driven Architecture: GPUI operates on an event-driven model, translating user input into application-specific actions.
Actions Decouple Logic: Actions are named commands that separate what happened from how it’s handled, improving modularity and testability.
actions! Macro: Use this macro to conveniently define your custom action structs.
cx.dispatch_action(): The primary method for triggering an action from UI elements (like buttons) or other parts of your application.
cx.defer_action(): Registers view-specific action handlers that respond to actions when the associated view (or its children) has focus.
cx.bind_keys(): Registers global keyboard shortcuts that dispatch actions, providing an alternative input method.
cx.notify() is Critical: Always call cx.notify() after changing a view’s state to ensure the UI re-renders and reflects those changes.
Embrace Source Diving: Due to GPUI’s active development, the Zed editor’s source code (especially crates/gpui) is your most authoritative reference for current API usage and best practices.

You now possess the tools to make your UI respond intelligently to user input. In the next chapter, we’ll refine the visual appeal of your applications by diving deeper into GPUI’s powerful styling system, allowing you to create truly polished interfaces.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.

Interacting with Your UI: Actions and Event Handling

// table of contents