Combobox

Material Design 3 combobox for selecting from a list of options with optional search and multi-select. Not intended for free-form long text entry where arbitrary values are expected.

Basic Usage

Use a combobox to choose from a short or filtered list. It combines text input and option selection in one compact control for faster discovery.

Apple
Banana
Cherry
Date
 
<ds-combobox>
  <div slot="option" data-value="apple">Apple</div>
  <div slot="option" data-value="banana">Banana</div>
</ds-combobox>

Initial Value

Provide a default value for single or multiple selection.

Single value
Apple
Banana
Cherry
Multiple values
HTML
CSS
JavaScript
Web Components 
<ds-combobox value="banana">
  <div slot="option" data-value="banana">Banana</div>
</ds-combobox>

<ds-combobox multiple value="css,javascript">
  <div slot="option" data-value="css">CSS</div>
  <div slot="option" data-value="javascript">JavaScript</div>
</ds-combobox>

Variants

Use single, multiple, or non-searchable variants as needed.

Single Selection

Only one option can be selected at a time.

Red
Green
Blue
 
<ds-combobox>
  <div slot="option" data-value="red">Red</div>
  <div slot="option" data-value="green">Green</div>
</ds-combobox>

Multiple Selection

Keep the list open to select multiple values.

Python
JavaScript
TypeScript
Rust
 
<ds-combobox multiple>
  <div slot="option" data-value="python">Python</div>
  <div slot="option" data-value="javascript">JavaScript</div>
</ds-combobox>

Non-Searchable

Disable search when users should only navigate with keys.

Small
Medium
Large
Extra Large
 
<ds-combobox searchable="false">
  <div slot="option">Small</div>
  <div slot="option">Medium</div>
</ds-combobox>

States

Use disabled to prevent interaction.

Option 1
Option 2
 
<ds-combobox disabled>
  <div slot="option">Option 1</div>
</ds-combobox>

Interactive Example

Track open, close, and change events.

HTML
CSS
JavaScript
Web Components

Event Log

API Reference

Attributes

Attribute Type Default Description
name string "" Form field name. The selection is submitted under it; without a name the field is left out.
required boolean false Whether something must be selected. Blocks the enclosing form's submission until satisfied.
open boolean false Whether the dropdown is visible
multiple boolean false Allow multiple selections
searchable boolean true Enable search input
disabled boolean false Disable interaction
placeholder string "Select an option" Text shown when no option selected
value string|array null Selected value(s)

Forms

Submits the selected value, and nothing with no selection. With multiple it submits one entry per selected value, like a multi-select. required means something must be selected. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.

Properties

Property Type Description
open boolean Get/set whether the dropdown is open
multiple boolean Get/set multiple selection mode
searchable boolean Get/set search input visibility
disabled boolean Get/set disabled state
value string|array Get/set selected value(s)

Events

Event Detail Description
ds-combobox:change { value, values } Fired when selection changes
ds-combobox:open — Fired when the dropdown opens
ds-combobox:close — Fired when the dropdown closes

Slots

Slot Description
option Option elements for selection

Methods

Method Parameters Description
show() none Opens the dropdown
close() none Closes the dropdown

CSS Parts

Part Description
container Main wrapper element
trigger Button that opens/closes the dropdown
dropdown Dropdown container
search-input Search input field
listbox Options container
option Individual option element

CSS Custom Properties

Property Description
--ds-combobox-width Combobox width
--ds-combobox-max-height Maximum dropdown height
--ds-combobox-height Trigger button height
--ds-combobox-search-height Search input height
--ds-combobox-option-height Option row height
--ds-combobox-padding-y Trigger vertical padding
--ds-combobox-padding-x Trigger horizontal padding
--ds-combobox-option-padding-y Option vertical padding
--ds-combobox-option-padding-x Option horizontal padding. Set option padding through these two properties: a padding rule on the slotted option has no effect.
--ds-combobox-icon-size Trigger icon size
--ds-combobox-bg-color Trigger and highlight background
--ds-combobox-dropdown-bg Dropdown and option background
--ds-combobox-text-color Base text color
--ds-combobox-border-color Trigger and dropdown border
--ds-combobox-hover-bg Hover background for options
--ds-combobox-selected-bg Selected option background
--ds-combobox-selected-color Selected option text color

Accessibility

  • ✅ Keyboard navigation with arrows, Enter, Escape
  • ✅ Uses listbox and option roles for screen readers
  • ✅ Announces selection changes via aria-selected
  • ✅ Focus returns to the trigger after close

Usage Guidelines

When to Use

  • When users need to search a list of options
  • For multi-select filters or tag selection
  • When options should show custom labels or metadata

When Not to Use

  • For very short lists where a simple select is faster
  • For binary choices where a checkbox or switch fits better

Best Practices

  • Keep option labels concise and scannable
  • Provide search when lists exceed 7-10 items
  • Use meaningful values in the data-value attribute