Overlays

Dropdown menu

A menu of actions that opens from a button, with check marks, radio choices and submenus.

use iced_cube::dropdown_menu::{
    self, Event, Output, State, checkbox_item, dropdown_menu, group_label, item,
    radio_item, separator, submenu,
};

API reference

Default: Items with icons and shortcut hints, a submenu, a disabled item and a destructive one. — **Default.** Items with icons and shortcut hints, a submenu, a disabled item and a destructive one.

Usage

The app owns a dropdown_menu::State and routes its events into it. When update returns an Output, the menu has already closed and updated its own check marks, so the app only acts on the choice. Read checkbox and radio values back with state.is_checked(id), or keep your own copy and call set_checked when it changes elsewhere.

The trigger is any element you pass in, usually a button whose message carries Event::Toggle. Escape and a click outside send Event::Close through on_event, and Escape inside a submenu closes just that submenu. The click that closes the menu goes no further, so a menu inside a dialog closes without closing the dialog too. Clicks inside the menu never reach the widgets underneath it, and a tooltip on the trigger stays hidden while the menu is open.

Moving the pointer over an item highlights it, and the keyboard moves the same highlight. The open menu handles its own keys before anything else sees them, so it needs no subscription. A closed menu claims no keys at all, so the arrow keys, Enter and Space stay free for the rest of your app. To open a menu from the keyboard, bind a chord to Action::Open and route presses from keys::subscription() through state.key_event, as the keyboard example does. The keyboard guide explains how keys reach each layer.

The menu opens on the side you ask for, or the opposite side when only that one has room for all of it. When neither does, it takes the roomier side and scrolls, so it never covers its trigger. A submenu opens beside its item, flipping to the other side near the edge of the window. On a screen too narrow for either, it drops below or above the item instead, so the item’s label stays visible.

When any item in a menu has an icon, a check mark or a radio dot, every row gets one leading slot, so all the labels start at the same place. A checked item shows its mark in that slot, and any other item shows its icon there, or leaves it empty.

Shortcut hints are only labels. Bind the keys themselves in your own keymap. The context menu uses the same entries and rows, opened with a right-click.

Examples

Checkbox items

Items that toggle a check mark, one of them disabled.

use iced::widget::{column, container, text};
use iced::{Element, Length};
use iced_cube::button;
use iced_cube::dropdown_menu::{
    Event, State, checkbox_item, dropdown_menu, group_label, separator,
};
use iced_cube::primitives::button::Variant;

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Panel {
    StatusBar,
    ActivityBar,
    Minimap,
}

#[derive(Debug, Clone)]
pub enum Message {
    Menu(Event<Panel>),
}

#[derive(Debug)]
pub struct Example {
    menu: State<Panel>,
}

impl Default for Example {
    fn default() -> Self {
        let mut menu = State::new([
            group_label("Appearance"),
            separator(),
            checkbox_item(Panel::StatusBar, "Status bar", true),
            checkbox_item(Panel::ActivityBar, "Activity bar", false).disabled(true),
            checkbox_item(Panel::Minimap, "Minimap", false),
        ]);
        let _ = menu.update(Event::Open);
        Self { menu }
    }
}

impl Example {
    pub fn update(&mut self, message: Message) {
        let Message::Menu(event) = message;
        let _ = self.menu.update(event);
    }

    pub fn view(&self) -> Element<'_, Message> {
        let shown: Vec<&str> = [Panel::StatusBar, Panel::ActivityBar, Panel::Minimap]
            .into_iter()
            .filter(|&panel| self.menu.is_checked(panel))
            .filter_map(|panel| self.menu.item(panel))
            .map(|item| item.label.as_str())
            .collect();
        let summary = match shown.as_slice() {
            [] => "Showing nothing".to_string(),
            shown => format!("Showing: {}", shown.join(", ")),
        };
        let trigger = button("View")
            .variant(Variant::Outline)
            .on_press(Message::Menu(Event::Toggle));

        column![
            text(summary).size(14),
            container(dropdown_menu(&self.menu, trigger).on_event(Message::Menu))
                .height(Length::Fill),
        ]
        .spacing(12)
        .width(240)
        .into()
    }
}

crates/gallery/src/stories/dropdown_menu/checkboxes.rs

Radio items

A group of items where choosing one unchecks the others.

use iced::widget::{column, container, text};
use iced::{Element, Length};
use iced_cube::button;
use iced_cube::dropdown_menu::{
    Event, Output, State, dropdown_menu, group_label, radio_item, separator,
};
use iced_cube::primitives::button::Variant;

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Position {
    Top,
    Bottom,
    Right,
}

#[derive(Debug, Clone)]
pub enum Message {
    Menu(Event<Position>),
}

#[derive(Debug)]
pub struct Example {
    menu: State<Position>,
    position: Position,
}

impl Default for Example {
    fn default() -> Self {
        let mut menu = State::new([
            group_label("Panel position"),
            separator(),
            radio_item(Position::Top, "Top", false),
            radio_item(Position::Bottom, "Bottom", true),
            radio_item(Position::Right, "Right", false),
        ]);
        let _ = menu.update(Event::Open);
        Self {
            menu,
            position: Position::Bottom,
        }
    }
}

impl Example {
    pub fn update(&mut self, message: Message) {
        let Message::Menu(event) = message;
        if let Some(Output::Selected(position)) = self.menu.update(event) {
            self.position = position;
        }
    }

    pub fn view(&self) -> Element<'_, Message> {
        let trigger = button("Panel")
            .variant(Variant::Outline)
            .on_press(Message::Menu(Event::Toggle));

        column![
            text(format!("Panel position: {:?}", self.position)).size(14),
            container(dropdown_menu(&self.menu, trigger).on_event(Message::Menu))
                .height(Length::Fill),
        ]
        .spacing(12)
        .width(240)
        .into()
    }
}

crates/gallery/src/stories/dropdown_menu/radio_items.rs

Submenu

A nested menu that opens beside its item, on hover or with the right arrow key.

use iced::widget::container;
use iced::{Element, Length};
use iced_cube::button;
use iced_cube::dropdown_menu::{Event, State, dropdown_menu, item, separator, submenu};
use iced_cube::primitives::button::Variant;

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Id {
    NewTab,
    NewWindow,
    Private,
    MoreTools,
    SavePage,
    Shortcut,
    NameWindow,
    DevTools,
    Print,
}

#[derive(Debug, Clone)]
pub enum Message {
    Menu(Event<Id>),
}

#[derive(Debug)]
pub struct Example {
    menu: State<Id>,
}

impl Default for Example {
    fn default() -> Self {
        let mut menu = State::new([
            item(Id::NewTab, "New tab").shortcut("Ctrl+T"),
            item(Id::NewWindow, "New window").shortcut("Ctrl+N"),
            item(Id::Private, "Private window")
                .shortcut("Shift+Ctrl+N")
                .disabled(true),
            submenu(
                Id::MoreTools,
                "More tools",
                [
                    item(Id::SavePage, "Save page as").shortcut("Ctrl+S"),
                    item(Id::Shortcut, "Create shortcut"),
                    item(Id::NameWindow, "Name window"),
                    separator(),
                    item(Id::DevTools, "Developer tools"),
                ],
            ),
            separator(),
            item(Id::Print, "Print").shortcut("Ctrl+P"),
        ]);
        let _ = menu.update(Event::Open);
        let _ = menu.update(Event::Highlight(Id::MoreTools));
        Self { menu }
    }
}

impl Example {
    pub fn update(&mut self, message: Message) {
        let Message::Menu(event) = message;
        let _ = self.menu.update(event);
    }

    pub fn view(&self) -> Element<'_, Message> {
        let trigger = button("File")
            .variant(Variant::Outline)
            .on_press(Message::Menu(Event::Toggle));

        container(dropdown_menu(&self.menu, trigger).on_event(Message::Menu))
            .width(Length::Fill)
            .height(Length::Fill)
            .into()
    }
}

crates/gallery/src/stories/dropdown_menu/submenu.rs

Keyboard shortcuts

The open menu resolves its own keys through the keymap, with typeahead for letters. The app binds Alt+ArrowDown to open it.

use iced::keyboard::key::Named;
use iced::widget::{column, container, text};
use iced::{Element, Length, Subscription};
use iced_cube::button;
use iced_cube::dropdown_menu::{
    self, Action, Event, Output, State, dropdown_menu, item, separator,
};
use iced_cube::keys::{self, Chord, Keymap};
use iced_cube::primitives::button::Variant;

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Edit {
    Undo,
    Redo,
    Cut,
    Copy,
    Paste,
    SelectAll,
}

#[derive(Debug, Clone)]
pub enum Message {
    Menu(Event<Edit>),
    Key(keys::Event),
}

#[derive(Debug)]
pub struct Example {
    menu: State<Edit>,
    keymap: Keymap<Action>,
    chosen: Option<Edit>,
}

impl Default for Example {
    fn default() -> Self {
        let mut menu = State::new([
            item(Edit::Undo, "Undo").shortcut("Ctrl+Z"),
            item(Edit::Redo, "Redo").shortcut("Ctrl+Y").disabled(true),
            separator(),
            item(Edit::Cut, "Cut").shortcut("Ctrl+X"),
            item(Edit::Copy, "Copy").shortcut("Ctrl+C"),
            item(Edit::Paste, "Paste").shortcut("Ctrl+V"),
            separator(),
            item(Edit::SelectAll, "Select all").shortcut("Ctrl+A"),
        ]);
        let _ = menu.update(Event::First);
        // Alt+ArrowDown opens the closed menu; the open menu handles the rest.
        let keymap = dropdown_menu::default_keymap()
            .bind(Chord::named(Named::ArrowDown).alt(), Action::Open);
        Self {
            menu,
            keymap,
            chosen: None,
        }
    }
}

impl Example {
    pub fn update(&mut self, message: Message) {
        let event = match message {
            Message::Menu(event) => Some(event),
            // Only presses nothing else captured arrive here, so an open
            // menu has already taken its own keys.
            Message::Key(key) => self.menu.key_event(&self.keymap, &key),
        };
        if let Some(Output::Activated(edit)) = event.and_then(|event| self.menu.update(event)) {
            self.chosen = Some(edit);
        }
    }

    pub fn view(&self) -> Element<'_, Message> {
        let chosen = match self.chosen {
            Some(edit) => format!("Chose {edit:?}"),
            None => "Nothing chosen yet".into(),
        };
        let trigger = button("Edit")
            .variant(Variant::Outline)
            .on_press(Message::Menu(Event::Toggle));

        column![
            text("Arrows move, Enter chooses, Escape closes, letters jump. Alt+ArrowDown opens.")
                .size(14),
            text(chosen).size(14),
            container(
                dropdown_menu(&self.menu, trigger)
                    .keymap(self.keymap.clone())
                    .on_event(Message::Menu)
            )
            .height(Length::Fill),
        ]
        .spacing(12)
        .width(Length::Fixed(560.0))
        .into()
    }

    pub fn subscription(&self) -> Subscription<Message> {
        keys::subscription().map(Message::Key)
    }
}

crates/gallery/src/stories/dropdown_menu/keyboard.rs

In a dialog

A menu inside a dialog. A click outside or Escape closes only the menu; the next one closes the dialog.

use iced::widget::{column, container, row, text};
use iced::{Alignment, Element, Length};
use iced_cube::dropdown_menu::{Event, Output, State, dropdown_menu, radio_item};
use iced_cube::overlay::dialog::{self, dialog};
use iced_cube::primitives::button::Variant;
use iced_cube::theme::{Tokens, text_size};
use iced_cube::{button, lucide};

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Access {
    View,
    Comment,
    Edit,
}

impl Access {
    fn label(self) -> &'static str {
        match self {
            Access::View => "Can view",
            Access::Comment => "Can comment",
            Access::Edit => "Can edit",
        }
    }
}

#[derive(Debug, Clone)]
pub enum Message {
    Open,
    Close,
    Menu(Event<Access>),
}

#[derive(Debug)]
pub struct Example {
    open: bool,
    menu: State<Access>,
    access: Access,
}

impl Default for Example {
    fn default() -> Self {
        let mut menu = State::new(
            [Access::View, Access::Comment, Access::Edit]
                .map(|access| radio_item(access, access.label(), access == Access::View)),
        );
        let _ = menu.update(Event::Open);
        let _ = menu.update(Event::Highlight(Access::Comment));
        Self {
            open: true,
            menu,
            access: Access::View,
        }
    }
}

impl Example {
    pub fn update(&mut self, message: Message) {
        match message {
            Message::Open => self.open = true,
            // Escape or a click outside closes the menu first, so the
            // dialog only closes once the menu is gone.
            Message::Close => self.open = false,
            Message::Menu(event) => {
                if let Some(Output::Selected(access)) = self.menu.update(event) {
                    self.access = access;
                }
            }
        }
    }

    pub fn view(&self) -> Element<'_, Message> {
        let trigger = button(self.access.label())
            .trailing_icon(lucide!(ChevronDown))
            .variant(Variant::Outline)
            .on_press(Message::Menu(Event::Toggle));
        let link = row![
            column![
                text("Anyone with the link").size(text_size::SM),
                text("No sign-in required")
                    .size(text_size::SM)
                    .style(|theme| text::Style {
                        color: Some(Tokens::of(theme).muted_foreground),
                    }),
            ]
            .width(Length::Fill),
            dropdown_menu(&self.menu, trigger)
                .width(160.0)
                .on_event(Message::Menu),
        ]
        .spacing(12)
        .align_y(Alignment::Center);

        let base = container(
            button("Share")
                .variant(Variant::Outline)
                .on_press(Message::Open),
        )
        .padding(24);

        dialog(base)
            .open(self.open)
            .title("Share document")
            .description("Choose what people with the link can do.")
            .body(link)
            .action(button("Done").on_press(Message::Close))
            .size(dialog::Size::Sm)
            .on_dismiss(Message::Close)
            .into()
    }
}

crates/gallery/src/stories/dropdown_menu/in_dialog.rs

API

Item	Description
`State::new(entries)`	Holds the entries, closed. Item ids must be unique, including those in submenus.
`item(id, label)`	An action. Add .icon(glyph), .shortcut("Ctrl+S"), .disabled(true) or .destructive(true).
`checkbox_item(id, label, checked)`	An item with a check mark that toggles when chosen.
`radio_item(id, label, checked)`	One choice among the radio items next to it. Choosing it unchecks the rest of that run.
`submenu(id, label, entries)`	Opens a nested menu to its right, on hover, click, Enter or the right arrow key.
`group_label(text) / separator()`	A heading for the items below it, and a line between groups.
`state.update(Event)`	Handles Open, Close, Toggle, Highlight, Next, Previous, First, Last, OpenSubmenu, CloseSubmenu, Activate, ActivateHighlighted and Typeahead. Returns Output::Activated, Toggled or Selected when an item is chosen, and closes the menu.
`state.is_open() / state.highlighted() / state.depth()`	Whether the menu is open, the highlighted item's id, and how many menus are open including submenus.
`state.item(id) / state.is_checked(id)`	An item by id, and whether a checkbox or radio item is checked.
`state.set_checked(id, bool) / state.set_disabled(id, bool)`	Changes an item from your own state, for example when a setting changes elsewhere.
`dropdown_menu(&state, trigger)`	Renders the trigger with the menu below it while it is open. Items render disabled until .on_event is set.
`.on_event(f)`	Maps menu events to your message. The trigger sends Event::Toggle itself.
`.side(Side) / .align(Align) / .gap(f32)`	Where the menu opens. Defaults to below the trigger, lined up with its left edge.
`.width(f32)`	Width of the menu and its submenus. Defaults to 224.
`.keymap(keymap)`	Replaces the default keymap the open menu resolves its keys with. Unbinding Escape there stops Escape closing the menu.
`overlay::menu::row_style(tokens, RowStatus, destructive)`	The colours of a row when idle, highlighted or disabled, shared by every menu and list, for reuse in custom menus.
`dropdown_menu::default_keymap()`	The default shortcuts as a Keymap<Action>. Bind, unbind or clear chords to change them. Open has no default chord.
`state.key_event(&keymap, &key)`	Resolves a key press through the keymap and, while the menu is open, turns letters and digits into typeahead. Route presses from keys::subscription through it to open a closed menu with a chord bound to Action::Open.
`action.event(&state)`	Turns a resolved Action into the Event to pass to state.update, or None when it does nothing. Only Open works while the menu is closed.

Keyboard

Default shortcuts. Every one can be changed or removed with a keymap; see Keyboard shortcuts.

Keys	Action
`ArrowDown`	`Next` Highlights the next enabled item, wrapping.
`ArrowUp`	`Previous` Highlights the previous enabled item, wrapping.
`Home`	`First` Highlights the first enabled item.
`End`	`Last` Highlights the last enabled item.
`Enter` or `Space`	`Activate` Chooses the highlighted item or opens its submenu.
`Escape`	`Close` Closes the innermost submenu, or the menu.
`ArrowRight`	`OpenSubmenu` Opens the highlighted submenu.
`ArrowLeft`	`CloseSubmenu` Closes the innermost submenu.