Combobox
Pick one or many from a searchable, grouped list: chips with avatars, highlighted matches, create-on-the-fly and full keyboard support.
oxyn add comboboxlet options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: None,
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Rendered from Rust at build time · goes live when visible
When to use
- Pick one or many values from a long, searchable list: assign people and agents, choose tools, tag a run.
- The user types a few letters and wants the right row highlighted and chosen without leaving the keyboard.
When not to use
- Several values in a compact field: use Multi-select instead.
- Pick one option in the text field's look: use Select instead.
- Several values in one field as chips: use Tag Input instead.
Installation
Combobox is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add comboboxuse crate::oxyn::{Combobox, PRIMITIVES_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{Combobox, PRIMITIVES_CSS};
Usage
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: None,
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Examples
Multiple
Chips with avatars, grouped list.
Code
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: None,
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Single
One value; the list closes after a pick.
Code
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
label: Some("Assign to".into()),
max_visible_tags: None,
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Overflow
+N past two chips.
Code
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: Some(1),
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Fuzzy
Letters in order match (Oxyn plus).
Code
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: None,
match_mode: "fuzzy",
max_selected: None,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}Capped
Up to three, with Select all (Oxyn plus).
Code
let options = vec![
ComboOption::new("maya", "Maya Patel").hint("Design").group("Team").avatar(),
ComboOption::new("coder", "Coder").hint("Agent").group("Agents").icon("code"),
];
rsx! {
Combobox {
options: options,
value: assignees(),
multiple: true,
label: Some("Assign to".into()),
creatable: true,
max_visible_tags: None,
max_selected: Some(3),
select_all: true,
on_change: move |ids: Vec<String>| assignees.set(ids),
}
}API reference
Combobox
| Prop | Type | Default | Description |
|---|---|---|---|
optionsrequired | Vec<ComboOption> | — | Options. |
value | Vec<String> | Default::default() | Starting values. |
multiple | bool | true | Pick many (chips) or one. |
placeholder | String | "Search…" | Placeholder. |
creatable | bool | Default::default() | Offer a create row when nothing matches exactly. |
create_label | String | "Create “…”" | Create row text; `…` becomes the typed text. |
max_visible_tags | Option<usize> | Default::default() | Show at most this many chips, the rest as `+N`. |
label | Option<String> | Default::default() | Visible label (also names the list). |
default_open | bool | Default::default() | Open right away. |
empty_text | String | "No results" | Shown when nothing matches. |
match_mode | String | "contains" | `contains` · `prefix` · `fuzzy`. |
max_selected | Option<usize> | Default::default() | Max picks. |
select_all | bool | Default::default() | Select all row. |
disabled | bool | Default::default() | Disabled. |
on_change | EventHandler<Vec<String>> | — | Changed. |
on_create | EventHandler<String> | — | Created an option. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| ↑or↓ | Open the list, then move between rows |
| HomeorEnd | First / last row |
| ↵ | Pick or unpick the active row (or create) |
| ⌫ | In the empty field: mark the last chip, press again to remove it |
| Esc | Close the list; when closed, clear the typed text |
| Tab | Close the list and move on |
Accessibility
- ARIA combobox: the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; the list is a grouped listbox.
- Picked rows carry aria-selected; the listbox is aria-multiselectable in multiple mode.
- Picks and removals are announced politely with the count.
- Focus stays in the input while clicking rows and chip × buttons.
From the spec
ARIA 1.2 combobox pattern: the input keeps focus, aria-activedescendant points at the active row; the list is a listbox (aria-multiselectable in multiple mode) with group headings as presentation. Picks and removals are announced politely with the count ("Added Maya Patel, 2 selected"). Chip × buttons are labelled and do not steal focus.
Motion & interaction
The list lifts in from the field edge and its height animates as rows filter. The checkbox fills and its tick draws. Chips grow in; +N rolls. The chevron turns 180°. Matched letters highlight without layout shift.
Timing
| Transition | Duration | Easing | Reduced motion |
|---|---|---|---|
| List open | 180 ms, 4 px lift | ease.out | 80 ms fade |
| List height | 214 ms | ease.out | instant |
| Check fill + tick | 220 ms + 240 ms draw | ease.out | drawn |
| Chip in | 160 ms | ease.out | 1 ms |
+N roll | 200 ms | ease.out | swap |
| Async debounce (Oxyn plus) | 200 ms | — | — |
Responsive behaviour
- The list is as wide as the field.
- Chips wrap and long names truncate, down to 320 px.
- Touch: 44 px rows, bigger chip buttons and 16 px input text.
Edge cases (spec)
Long labels truncate in rows and chips. Very long lists scroll inside 280 px; the active row scrolls into view. Typing a value that exists exactly hides Create. Fuzzy match keeps order of letters. Narrow screens: the list matches the field width; touch rows are 44 px. RTL: chips and checkmarks mirror.
Notes for AI
- Import
Comboboxfromoxyn_dioxusand includePRIMITIVES_CSSplus the token stylesheet once. - A GPUI version exists:
ComboboxElinoxyn_gpui. - Props to set first:
options. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.