/build-gpui-apps

Popover

Popover component for displaying floating content that appears when interacting with a trigger element. Supports multiple positioning options, custom content, different trigger methods, and automatic dismissal behaviors. Perfect for tooltips, menus, forms, and other contextual information.

Import

use gpui_kit::component::popover::{Popover};

Usage

Basic Popover

:::info Any element that implements Selectable can be used as a trigger, for example, a Button.

Any element that implements RenderOnce or Render can be used as popover content, use .child(...) to add children directly. :::

use gpui_kit::ParentElement as _;
use gpui_kit::component::{button::Button, popover::Popover};

Popover::new("basic-popover")
    .trigger(Button::new("trigger").label("Click me").outline())
    .child("Hello, this is a popover!")
    .child("It appears when you click the button.")

Popover with Custom Positioning

The anchor method names the popover's own anchor, not the trigger's corner. Top* anchors open below the trigger, Bottom* anchors open above it, LeftCenter opens to the right, and RightCenter opens to the left. The popup clamps to the window without changing its anchor or flipping.

use gpui_kit::{Anchor, px};
use gpui_kit::component::popover::Popover;

Popover::new("anchored")
    .anchor(Anchor::TopCenter)
    .offset(px(8.))
    .arrow(true)
    .trigger(Button::new("details").label("Details"))
    .child("Contextual details")

The arrow follows the anchor's leading, center, or trailing alignment and is inset as needed to avoid rounded corners. It adds 0.375rem to the surface distance and uses the surface background, falling back to the theme's popover color. Neither offset nor arrow changes the positioning strategy.

For example, Anchor::TopLeft places the popover just below the trigger, left-aligned to it:

[ Trigger ]
┌──────────────┐
│   Popover    │
└──────────────┘

use gpui_kit::component::Anchor;

// Below the trigger: name the popover's top anchor
Popover::new("top-left")
    .anchor(Anchor::TopLeft)
    .trigger(Button::new("btn").label("Top Left").outline())
    .child("Below the trigger, aligned left")

Popover::new("top-center")
    .anchor(Anchor::TopCenter)
    .trigger(Button::new("btn").label("Top Center").outline())
    .child("Below the trigger, centered")

Popover::new("top-right")
    .anchor(Anchor::TopRight)
    .trigger(Button::new("btn").label("Top Right").outline())
    .child("Below the trigger, aligned right")

// Above the trigger: name the popover's bottom anchor
Popover::new("bottom-left")
    .anchor(Anchor::BottomLeft)
    .trigger(Button::new("btn").label("Bottom Left").outline())
    .child("Above the trigger, aligned left")

Popover::new("bottom-center")
    .anchor(Anchor::BottomCenter)
    .trigger(Button::new("btn").label("Bottom Center").outline())
    .child("Above the trigger, centered")

Popover::new("bottom-right")
    .anchor(Anchor::BottomRight)
    .trigger(Button::new("btn").label("Bottom Right").outline())
    .child("Above the trigger, aligned right")

View in Popover

You can add any Entity<T> that implemented Render as the popover content.

let view = cx.new(|_| MyView::new());

Popover::new("form-popover")
    .anchor(Anchor::BottomLeft)
    .trigger(Button::new("show-form").label("Open Form").outline())
    .child(view.clone())

Add content by content method

The content method allows you to create more complex popover content using a closure. This is useful when you need to build dynamic content or need access to the popover's context.

This method will let us to have &mut PopoverState, &mut Window and &mut Context<PopoverState> parameters in the closure is to allow you to interact with the popover's state and the overall application context if needed.

:::warning This content callback will called every time on render the popover. So, you should avoid creating new elements or entities in the content closure or other heavy operations that may impact performance. :::

And content will works with child, children methods together.

use gpui_kit::ParentElement as _;
use gpui_kit::component::popover::Popover;

Popover::new("complex-popover")
    .anchor(Anchor::BottomLeft)
    .trigger(Button::new("complex").label("Complex Content").outline())
    .content(|_, _, _| {
        div()
            .child("This popover has complex content.")
            .child(
                Button::new("action-btn")
                    .label("Perform Action")
                    .outline()
            )
    })

Right-Click Popover

Sometimes you may want to show a popover on right-click, for example, to create a special your ownen context menu. The mouse_button method allows you to specify which mouse button triggers the popover.

use gpui_kit::MouseButton;

Popover::new("context-menu")
    .anchor(Anchor::BottomRight)
    .mouse_button(MouseButton::Right)
    .trigger(Button::new("right-click").label("Right Click Me").outline())
    .child("Context Menu")
    .child(Separator::horizontal())
    .child("This is a custom context menu.")

Dismiss Popover manually

If you want to dismiss the popover programmatically from within the content, you can emit a DismissEvent. In this case, you should use content method to create the popover content so you have access to the cx: &mut Context<PopoverState>.

use gpui_kit::component::{DismissEvent, popover::Popover};

Popover::new("dismiss-popover")
    .trigger(Button::new("dismiss").label("Dismiss Popover").outline())
    .content(|_, cx| {
        div()
            .child("Click the button below to dismiss this popover.")
            .child(
                Button::new("close-btn")
                    .label("Close Popover")
                    .on_click(cx.listener(|_, _, _, cx| {
                        // NOTE: Here `cx` is `&mut Context<PopoverState>` type, so we can emit DismissEvent.
                        cx.emit(DismissEvent);
                    }))
            )
    })

Styling Popover

Like the others components in GPUI Component, the appearance(false) method can be used to disable the default styling of the popover, allowing you to fully customize its appearance.

And the Popover has implemented the Styled trait, so you can use all the styling methods provided by GPUI to style the popover content as you like.

// For custom styled popovers or when you want full control
Popover::new("custom-popover")
    .appearance(false)
    .trigger(Button::new("custom").label("Custom Style"))
    .bg(cx.theme().accent)
    .text_color(cx.theme().accent_foreground)
    .p_6()
    .rounded_xl()
    .shadow_2xl()
    .child("Fully custom styled popover")

Control Open State

There have open and on_open_change methods to control the open state of the popover programmatically.

This is useful when you want to synchronize the popover's open state with other UI elements or application state.

:::tip When you use open to control the popover's open state, that means you have take full control of it, so you need to update the state in on_open_change callback to keep the popover working correctly. :::

use gpui_kit::component::popover::Popover;

struct MyView {
    popover_open: bool,
}

Popover::new("controlled-popover")
    .open(self.open)
    .on_open_change(cx.listener(|this, open: &bool, _, cx| {
        this.popover_open = *open;
        cx.notify();
    }))
    .trigger(Button::new("control-btn").label("Control Popover").outline())
    .child("This popover's open state is controlled programmatically.")

Default Open

The default_open method allows you to set the initial open state of the popover when it is first rendered.

Please note that if you use the open method to control the popover's open state, the default_open setting will be ignored.

use gpui_kit::component::popover::Popover;

Popover::new("default-open-popover")
    .default_open(true)
    .trigger(Button::new("default-open-btn").label("Default Open").outline())
    .child("This popover is open by default when first rendered.")

Custom Trigger

A trigger is any element that implements Selectable. While the popover is open, it calls open(true) on the trigger — not selected(true) — so a trigger can tell "my popover is showing" apart from "I am the selected item".

open and is_open default to selected and is_selected, so a trigger that only implements the selected state keeps working unchanged, and a Button trigger looks the same open as it does selected. Override them when your element already uses selected for something else, such as a sidebar row that is selected when it is the current view:

use gpui_kit::component::Selectable;

struct SidebarRow {
    /// This row is the current view.
    selected: bool,
    /// This row's account popover is showing.
    open: bool,
}

impl Selectable for SidebarRow {
    fn selected(mut self, selected: bool) -> Self {
        self.selected = selected;
        self
    }

    fn is_selected(&self) -> bool {
        self.selected
    }

    fn open(mut self, open: bool) -> Self {
        self.open = open;
        self
    }

    fn is_open(&self) -> bool {
        self.open
    }
}

Documentation license: original prose and illustrations for which GPUI Kit holds licensing rights are also offered under CC BY 4.0. When copying or adapting, credit GPUI Kit, link the source (https://gpui-kit.com/component/popover) and https://creativecommons.org/licenses/by/4.0/, and indicate changes. Code examples and software source use Apache-2.0; third-party material retains its terms; existing Apache-2.0 permissions remain.

Bundled from GPUI Kit. Documentation prose: CC BY 4.0; code examples: Apache-2.0. Changes: documentation links localized, asset URLs made absolute, and this attribution added.