Component 12 of 60

Combobox

An input paired with a searchable list of choices.

site/src/previews/combobox.rs

Starting the preview. GPUI compiles to WebAssembly, so the first load takes a few seconds. This browser has neither WebGPU nor WebGL 2, so the live preview cannot run. The code on this page still works. The preview did not start.

fn combobox_preview(&self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
    let state = window.use_keyed_state("combobox_preview", cx, |window, cx| {
        let mut state = SelectState::new(
            [
                SelectItem::new("apple", "Apple"),
                SelectItem::new("banana", "Banana"),
                SelectItem::new("orange", "Orange").disabled(true),
                SelectItem::new("pear", "Pear"),
            ],
            window,
            cx,
        );
        state.set_value(Some("pear".into()), window, cx);
        state
    });
    gpuicn::combobox::combobox(&state)
        .aria_label("Fruit")
        .placeholder("Search a fruit…")
        .w(px(240.))
}

Combobox, running in the browser. The second tab shows the preview's own source, which includes its layout and demo state. For the smallest working example, see Usage below. Download the whole showcase for its imports and helpers.

Installation

After the one-time setup, run the command from your app root. The CLI writes the modules and keeps src/ui/mod.rs in step.

gpuicn add combobox

If you prefer to copy the files by hand, declare them yourself:

// src/ui/mod.rs
pub mod theme;
pub mod input;
pub mod field;
pub mod select;
pub mod combobox;

// src/main.rs
mod ui;

Usage

Put this in a view module and return example(window, cx) from its render method.

use crate::ui::combobox::*;
use crate::ui::select::{SelectItem, SelectState};
use gpui_kit::{App, IntoElement, Window};

fn example(window: &mut Window, cx: &mut App) -> impl IntoElement {
    let state = window.use_keyed_state("fruit", cx, |window, cx| {
        SelectState::new(
            [
                SelectItem::new("apple", "Apple"),
                SelectItem::new("pear", "Pear"),
            ],
            window,
            cx,
        )
    });
    combobox(&state)
        .aria_label("Fruit")
        .placeholder("Choose a fruit…")
}

API reference

pub fn combobox(state: &Entity<SelectState>) -> Select

Search the options and commit a listed value; subscribe to the state's change events.

Installed source, 12 lines

//! Editable Nova selection using the shared Kit-backed collection state.
use super::select::{Mode, Select};
pub use super::select::{SelectEvent, SelectItem, SelectState};
use gpui_kit::Entity;

/// Search the options and commit a listed value; subscribe to the state's change events.
pub fn combobox(state: &Entity<SelectState>) -> Select {
    let mut select = Select::new(state);
    select.mode = Mode::Combobox;
    select
}

Platform notes

Visual reference: shadcn/ui 4.19.0, Neutral Nova. Implementation: crates/ui/registry/combobox/combobox.rs, using GPUI Kit 0.6.4.

A retained SelectState owns a Kit text editor and one selected option. The query filters choices. Arrow keys skip disabled options, Enter commits and Escape closes and restores focus. Multiple selection and chips are outside this API.

The Rust source and Usage example define the supported API. Browser DOM/CSS behavior, exact exit animations and cross-platform screen-reader parity are not implied by the native component. See migration qualification for the checks completed on this revision.