iced_palette

Work in progress. This crate is early-stage and not yet polished. APIs may change without notice between releases.

AI disclaimer. Parts of this library and its documentation were written with the assistance of AI tools. Review the code before relying on it in production.

A command palette widget for Iced applications, with VS Code / Sublime Text-style fuzzy search.

iced_palette gives you a searchable, keyboard-navigable command overlay that you compose into your own view. It is generic over your application's Message type and styles itself from the active Iced theme, so it blends into your app out of the box.

Features

• Fuzzy search with Sublime Text-style scoring (word-boundary, consecutive-match, and start-of-string bonuses) and live match highlighting.
• Keyboard navigation with wrapping, mouse hover selection, and click-outside-to-close.
• Optional per-command descriptions, categories, keyboard shortcuts (with platform-aware display), and search keywords.
• Submenus / nested command lists.
• Theme-aware styling via the host application's Iced theme.
• Two API styles: a builder-based widget API and a simpler function API.

Installation

[dependencies]
iced_palette = "0.1"
iced = { version = "0.14", features = ["advanced"] }

Quick start (widget API)

Keep a PaletteState in your application state and render Palette in your view while it is open.

use iced_palette::{Palette, PaletteState, command, Shortcut};

struct App {
    palette: PaletteState,
}

#[derive(Debug, Clone)]
enum Message {
    QueryChanged(String),
    CommandSelected(&'static str),
    PaletteClosed,
    Save,
}

// Define your commands (typically built once):
let commands = vec![
    command("save", "Save File")
        .description("Save the current file")
        .shortcut(Shortcut::cmd('s'))
        .action(Message::Save),
];

// In your view, overlay the palette when open:
if self.palette.is_open() {
    iced::widget::stack![
        main_content,
        Palette::new(&self.palette, &commands)
            .on_query_change(Message::QueryChanged)
            .on_select(Message::CommandSelected)
            .on_close(|| Message::PaletteClosed),
    ]
    .into()
} else {
    main_content.into()
}

Opening the palette returns a Task that focuses the search input:

// In your update function:
Message::TogglePalette => self.palette.toggle(),
Message::QueryChanged(q) => { self.palette.set_query(q); Task::none() }
Message::PaletteClosed => { self.palette.close(); Task::none() }

PaletteState owns the open/closed flag, query, selection index, and submenu stack. Use open, close, toggle, set_query, navigate_up, navigate_down, enter_submenu, and go_back to drive it from your update.

Function API

If you prefer to manage the palette state yourself, command_palette (and command_palette_styled for custom PaletteConfig) render the overlay directly from loose arguments. Note that here on_select yields the display index of the filtered list; map it back to the original command with get_filtered_command_index.

use iced_palette::{command_palette, get_filtered_command_index};

if palette_open {
    iced::widget::stack![
        main_view,
        command_palette(
            &query,
            &commands,
            selected_index,
            Message::QueryChanged,
            Message::Select,     // receives the display index
            Message::Navigate,   // hover -> display index
            || Message::Cancel,
        ),
    ]
}

Keyboard shortcuts and subscriptions

Iced subscription closures cannot capture state, so the keyboard subscription itself lives in your application. iced_palette provides the stateless building blocks:

• is_toggle_shortcut(key, modifiers) — matches Ctrl/Cmd+Space.
• find_matching_shortcut(commands, key, modifiers) — returns the matching command id (recurses into submenus).
• collect_shortcuts(commands) — all (id, Shortcut) pairs, including submenus.
• navigate_up / navigate_down — wrapping index math for arrow-key handling.

License

MIT