Combobox

<wa-combobox>

Since 3.1

experimental

Pro

Comboboxes combine a text input with a listbox, allowing users to filter and select from predefined options or enter custom values.

Comboboxes combine a text input with a listbox, allowing users to filter a list of options and select one or more values. This component follows the ARIA APG Combobox pattern and uses live region announcements for result filtering in screen readers.

                
  Option 1
  Option 2
  Option 3
  Option 4
  Option 5
  Option 6

<wa-combobox name="foo" label="Type to filter...">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
  <wa-option value="option-4">Option 4</wa-option>
  <wa-option value="option-5">Option 5</wa-option>
  <wa-option value="option-6">Option 6</wa-option>
</wa-combobox>

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples Jump to heading

Labels Jump to heading

Use the label attribute to give the combobox an accessible label. For labels that contain HTML, use the label slot instead.

                
  Apple
  Banana
  Orange

<wa-combobox label="Choose a fruit">
  <wa-option value="apple">Apple</wa-option>
  <wa-option value="banana">Banana</wa-option>
  <wa-option value="orange">Orange</wa-option>
</wa-combobox>

Hint Jump to heading

Add descriptive hint to a combobox with the hint attribute. For hints that contain HTML, use the hint slot instead.

                
  Apple
  Banana
  Cherry
  Grape
  Orange

<wa-combobox label="Favorite Fruit" hint="Start typing to filter options.">
  <wa-option value="apple">Apple</wa-option>
  <wa-option value="banana">Banana</wa-option>
  <wa-option value="cherry">Cherry</wa-option>
  <wa-option value="grape">Grape</wa-option>
  <wa-option value="orange">Orange</wa-option>
</wa-combobox>

Placeholders Jump to heading

Use the placeholder attribute to add a placeholder.

                
  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Type to search...">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Clearable Jump to heading

Use the with-clear attribute to make the control clearable. The clear button only appears when the combobox has a value or text input.

                
  Option 1
  Option 2
  Option 3

<wa-combobox with-clear value="option-1">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Autocomplete Modes Jump to heading

The autocomplete attribute controls how options are filtered and presented.

List Autocomplete (Default) Jump to heading

Options are filtered as you type, showing only matching options. The typed value is preserved unless you select an option.

                
  Alabama
  Alaska
  Arizona
  Arkansas
  California
  Colorado

<wa-combobox autocomplete="list" label="List Autocomplete" placeholder="Type to filter...">
  <wa-option value="alabama">Alabama</wa-option>
  <wa-option value="alaska">Alaska</wa-option>
  <wa-option value="arizona">Arizona</wa-option>
  <wa-option value="arkansas">Arkansas</wa-option>
  <wa-option value="california">California</wa-option>
  <wa-option value="colorado">Colorado</wa-option>
</wa-combobox>

No Autocomplete Jump to heading

Options are not filtered; all options are shown regardless of what is typed.

                
  Recent Search 1
  Recent Search 2
  Recent Search 3

<wa-combobox autocomplete="none" label="No Autocomplete" placeholder="Type anything...">
  <wa-option value="recent-1">Recent Search 1</wa-option>
  <wa-option value="recent-2">Recent Search 2</wa-option>
  <wa-option value="recent-3">Recent Search 3</wa-option>
</wa-combobox>

Allow Custom Values Jump to heading

By default, the combobox only accepts values that match an option. Use allow-custom-value to let users enter arbitrary values.

                
  Red
  Green
  Blue

<wa-combobox allow-custom-value label="Enter or select a color" placeholder="Type a color...">
  <wa-option value="red">Red</wa-option>
  <wa-option value="green">Green</wa-option>
  <wa-option value="blue">Blue</wa-option>
</wa-combobox>

Custom Filter Function Jump to heading

You can provide a custom filter function to control how options are matched. The function receives the option element and the current query string, and should return true to show the option or false to hide it.

By default, the combobox filters options that contain the query anywhere in the label, but you can customize this to implement fuzzy matching, prefix-only matching, or apply any other filtering logic.

                
  Apple
  Pineapple
  Banana
  Grape
  Grapefruit

<wa-combobox label="Search (includes match)" placeholder="Search anywhere in text..." class="custom-filter">
  <wa-option value="apple">Apple</wa-option>
  <wa-option value="pineapple">Pineapple</wa-option>
  <wa-option value="banana">Banana</wa-option>
  <wa-option value="grape">Grape</wa-option>
  <wa-option value="grapefruit">Grapefruit</wa-option>
</wa-combobox>

<script type="module">
  await customElements.whenDefined('wa-combobox');
  const combobox = document.querySelector('.custom-filter');

  // Custom filter that matches anywhere in the label (not just the start)
  combobox.filter = (option, query) => {
    return option.label.toLowerCase().includes(query.toLowerCase());
  };
</script>

Appearance Jump to heading

Use the appearance attribute to change the combobox's visual appearance.

                
  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

<wa-combobox appearance="filled" placeholder="Filled">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>
<br />
<wa-combobox appearance="filled-outlined" placeholder="Filled Outlined">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>
<br />
<wa-combobox appearance="outlined" placeholder="Outlined">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Pill Jump to heading

Use the pill attribute to give comboboxes rounded edges.

                
  Option 1
  Option 2
  Option 3

<wa-combobox pill placeholder="Search...">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Disabled Jump to heading

Use the disabled attribute to disable a combobox.

                
  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Disabled" disabled>
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Multiple Jump to heading

To allow multiple options to be selected, use the multiple attribute. In multiple mode, selected options appear as tags and the input is used for filtering. It's a good practice to use with-clear when this option is enabled.

                
  Option 1
  Option 2
  Option 3
  Option 4
  Option 5
  Option 6

<wa-combobox label="Select Multiple" multiple with-clear placeholder="Type to filter...">
  <wa-option value="option-1" selected>Option 1</wa-option>
  <wa-option value="option-2" selected>Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
  <wa-option value="option-4">Option 4</wa-option>
  <wa-option value="option-5">Option 5</wa-option>
  <wa-option value="option-6">Option 6</wa-option>
</wa-combobox>

In multiple mode, the text input is used for filtering options only. After selecting an option, the input is cleared so you can continue filtering and selecting more options.

Setting Initial Values Jump to heading

Use the selected attribute on individual options to set the initial selection, similar to native HTML.

                
  Option 1
  Option 2
  Option 3
  Option 4

<wa-combobox label="Pre-selected option">
  <wa-option value="option-1" selected>Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
  <wa-option value="option-4">Option 4</wa-option>
</wa-combobox>

For multiple selections, apply it to all selected options.

                
  Option 1
  Option 2
  Option 3
  Option 4

<wa-combobox multiple with-clear>
  <wa-option value="option-1" selected>Option 1</wa-option>
  <wa-option value="option-2" selected>Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
  <wa-option value="option-4">Option 4</wa-option>
</wa-combobox>

Framework users can bind directly to the value property for reactive data binding and form state management.

Grouping Options Jump to heading

Use <wa-divider> to group listbox items visually. You can also use <small> to provide labels, but they won't be announced by most assistive devices.

                
  Fruits
  Apple
  Banana
  Orange
  
  Vegetables
  Carrot
  Broccoli
  Spinach

<wa-combobox label="Grouped Options">
  <small>Fruits</small>
  <wa-option value="apple">Apple</wa-option>
  <wa-option value="banana">Banana</wa-option>
  <wa-option value="orange">Orange</wa-option>
  <wa-divider></wa-divider>
  <small>Vegetables</small>
  <wa-option value="carrot">Carrot</wa-option>
  <wa-option value="broccoli">Broccoli</wa-option>
  <wa-option value="spinach">Spinach</wa-option>
</wa-combobox>

Sizes Jump to heading

Use the size attribute to change a combobox's size.

                
  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Small" size="small">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

<br />

<wa-combobox placeholder="Medium" size="medium">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

<br />

<wa-combobox placeholder="Large" size="large">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Placement Jump to heading

The preferred placement of the combobox's listbox can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom.

                
  Option 1
  Option 2
  Option 3

<wa-combobox placement="top" placeholder="Opens above">
  <wa-option value="option-1">Option 1</wa-option>
  <wa-option value="option-2">Option 2</wa-option>
  <wa-option value="option-3">Option 3</wa-option>
</wa-combobox>

Start & End Decorations Jump to heading

Use the start and end slots to add presentational elements like <wa-icon> within the combobox.

                
  New York
  Los Angeles
  Chicago

  New York
  Los Angeles
  Chicago

  New York
  Los Angeles
  Chicago

<wa-combobox placeholder="Search locations..." size="small" with-clear>
  <wa-icon slot="start" name="magnifying-glass"></wa-icon>
  <wa-icon slot="end" name="location-dot"></wa-icon>
  <wa-option value="new-york">New York</wa-option>
  <wa-option value="los-angeles">Los Angeles</wa-option>
  <wa-option value="chicago">Chicago</wa-option>
</wa-combobox>
<br />
<wa-combobox placeholder="Search locations..." size="medium" with-clear>
  <wa-icon slot="start" name="magnifying-glass"></wa-icon>
  <wa-icon slot="end" name="location-dot"></wa-icon>
  <wa-option value="new-york">New York</wa-option>
  <wa-option value="los-angeles">Los Angeles</wa-option>
  <wa-option value="chicago">Chicago</wa-option>
</wa-combobox>
<br />
<wa-combobox placeholder="Search locations..." size="large" with-clear>
  <wa-icon slot="start" name="magnifying-glass"></wa-icon>
  <wa-icon slot="end" name="location-dot"></wa-icon>
  <wa-option value="new-york">New York</wa-option>
  <wa-option value="los-angeles">Los Angeles</wa-option>
  <wa-option value="chicago">Chicago</wa-option>
</wa-combobox>

Custom Tags Jump to heading

When multiple options can be selected, you can provide custom tags by passing a function to the getTag property. Your function can return a string of HTML, a Lit Template, or an HTMLElement. The getTag() function will be called for each option. The first argument is an <wa-option> element and the second argument is the tag's index (its position in the tag list).

Remember that custom tags are rendered in a shadow root. To style them, you can use the style attribute in your template or you can add your own parts and target them with the ::part() selector.

                
    Email
  
    Phone
  
    Chat

<wa-combobox placeholder="Select contacts..." multiple with-clear class="custom-tag-combobox">
  <wa-option value="email" selected>
    <wa-icon slot="start" name="envelope" variant="solid"></wa-icon>
    Email
  </wa-option>
  <wa-option value="phone" selected>
    <wa-icon slot="start" name="phone" variant="solid"></wa-icon>
    Phone
  </wa-option>
  <wa-option value="chat">
    <wa-icon slot="start" name="comment" variant="solid"></wa-icon>
    Chat
  </wa-option>
</wa-combobox>

<script type="module">
  await customElements.whenDefined('wa-combobox');
  const combobox = document.querySelector('.custom-tag-combobox');
  await combobox.updateComplete;

  combobox.getTag = (option, index) => {
    // Use the same icon used in wa-option
    const name = option.querySelector('wa-icon[slot="start"]').name;

    // You can return a string, a Lit Template, or an HTMLElement here
    // Important: include data-value so the tag can be removed properly
    return `
      <wa-tag with-remove data-value="${option.value}">
        <wa-icon name="${name}"></wa-icon>
        ${option.label}
      </wa-tag>
    `;
  };
</script>

Be sure you trust the content you are outputting! Passing unsanitized user input to getTag() can result in XSS vulnerabilities.

When using custom tags with with-remove, you must include the data-value attribute set to the option's value. This allows the select to identify which option to deselect when the tag's remove button is clicked.

Importing Jump to heading

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN

npm

React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code.

import '@awesome.me/webawesome/dist/components/combobox/combobox.js';

To manually import this component from React, use the following code.

import WaCombobox from '@awesome.me/webawesome/dist/react/combobox';

Slots Jump to heading

Learn more about using slots.

Name	Description
(default)	The listbox options. Must be `<wa-option>` elements. You can use `<wa-divider>` to group items visually.
`label`	The input's label. Alternatively, you can use the `label` attribute.
`start`	An element, such as `<wa-icon>`, placed at the start of the combobox.
`end`	An element, such as `<wa-icon>`, placed at the end of the combobox.
`clear-icon`	An icon to use in lieu of the default clear icon.
`expand-icon`	The icon to show when the control is expanded and collapsed. Rotates on open and close.
`hint`	Text that describes how to use the input. Alternatively, you can use the `hint` attribute.

Attributes & Properties Jump to heading

Learn more about attributes and properties.

Name	Description	Reflects
`validationTarget`	Where to anchor native constraint validation
`inputValue`	The current text value in the input field. Type `string` Default `''`
`name` `name`	The name of the combobox, submitted as a name/value pair with form data. Type `string` Default `''`
`value` `value`	The combobox's value. This will be a string for single select or an array for multi-select.
`size` `size`	The combobox's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`placeholder` `placeholder`	Placeholder text to show as a hint when the combobox is empty. Type `string` Default `''`
`multiple` `multiple`	Allows more than one option to be selected. Type `boolean` Default `false`
`maxOptionsVisible` `max-options-visible`	The maximum number of selected options to show when `multiple` is true. After the maximum, "+n" will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit. Type `number` Default `3`
`disabled` `disabled`	Disables the combobox control. Type `boolean` Default `false`
`withClear` `with-clear`	Adds a clear button when the combobox is not empty. Type `boolean` Default `false`
`open` `open`	Indicates whether or not the combobox is open. You can toggle this attribute to show and hide the menu, or you can use the `show()` and `hide()` methods and this attribute will reflect the combobox's open state. Type `boolean` Default `false`
`appearance` `appearance`	The combobox's visual appearance. Type `'filled' \| 'outlined' \| 'filled-outlined'` Default `'outlined'`
`pill` `pill`	Draws a pill-style combobox with rounded edges. Type `boolean` Default `false`
`label` `label`	The combobox's label. If you need to display HTML, use the `label` slot instead. Type `string` Default `''`
`placement` `placement`	The preferred placement of the combobox's menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport. Type `'top' \| 'bottom'` Default `'bottom'`
`hint` `hint`	The combobox's hint. If you need to display HTML, use the `hint` slot instead. Type `string` Default `''`
`withLabel` `with-label`	Used for SSR purposes when a label is slotted in. Will show the label on first render. Type `boolean` Default `false`
`withHint` `with-hint`	Used for SSR purposes when hint is slotted in. Will show the hint on first render. Type `boolean` Default `false`
`required` `required`	The combobox's required attribute. Type `boolean` Default `false`
`autocomplete` `autocomplete`	The autocomplete behavior of the combobox. - `list`: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the combobox. The character string the user has typed will become the value of the combobox unless the user selects a value in the popup. - `none`: The combobox is editable, and when the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the combobox. Type `'list' \| 'none'` Default `'list'`
`allowCustomValue` `allow-custom-value`	When true, allows the user to enter a value that doesn't match any of the options. Only applies to single-select comboboxes. When false, the combobox will only accept values that match an option. Type `boolean` Default `false`
`filter`	A function that customizes how options are filtered based on the input value. The function receives the option and the current input query string. Return `true` to include the option in the filtered list, `false` to exclude. By default, options are filtered by checking if the option's label contains the query (case-insensitive). Type `((option: WaOption, query: string) => boolean) \| null` Default `null`
`getTag`	A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second is the current tag's index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value. Type `(option: WaOption, index: number) => TemplateResult \| string \| HTMLElement`

Methods Jump to heading

Learn more about methods.

Name	Description	Arguments
`show()`	Shows the listbox.
`hide()`	Hides the listbox.
`focus()`	Sets focus on the control.	`options: FocusOptions`
`blur()`	Removes focus from the control.

Events Jump to heading

Learn more about events.

Name	Description
`input`	Emitted when the control receives input.
`change`	Emitted when the control's value changes.
`focus`	Emitted when the control gains focus.
`blur`	Emitted when the control loses focus.
`wa-clear`	Emitted when the control's value is cleared.
`wa-show`	Emitted when the combobox's menu opens.
`wa-after-show`	Emitted after the combobox's menu opens and all animations are complete.
`wa-hide`	Emitted when the combobox's menu closes.
`wa-after-hide`	Emitted after the combobox's menu closes and all animations are complete.
`wa-invalid`	Emitted when the form control has been checked for validity and its constraints aren't satisfied.

CSS custom properties Jump to heading

Learn more about CSS custom properties.

Name	Description
`--show-duration`	The duration of the show animation. Default `100ms`
`--hide-duration`	The duration of the hide animation. Default `100ms`
`--tag-max-size`	When using `multiple`, the max size of tags before their content is truncated. Default `10ch`

Custom States Jump to heading

Learn more about custom states.

Name	Description	CSS selector
`blank`	The combobox is empty.	`:state(blank)`
`disabled`	The combobox is disabled.	`:state(disabled)`

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description	CSS selector
`form-control`	The form control that wraps the label, input, and hint.	`::part(form-control)`
`form-control-label`	The label's wrapper.	`::part(form-control-label)`
`form-control-input`	The combobox's wrapper.	`::part(form-control-input)`
`hint`	The hint's wrapper.	`::part(hint)`
`combobox`	The container the wraps the start, end, value, clear icon, and expand button.	`::part(combobox)`
`start`	The container that wraps the `start` slot.	`::part(start)`
`end`	The container that wraps the `end` slot.	`::part(end)`
`combobox-input`	The text input element.	`::part(combobox-input)`
`listbox`	The listbox container where options are slotted.	`::part(listbox)`
`tags`	The container that houses option tags when `multiselect` is used.	`::part(tags)`
`tag`	The individual tags that represent each multiselect option.	`::part(tag)`
`tag__content`	The tag's content part.	`::part(tag__content)`
`tag__remove-button`	The tag's remove button.	`::part(tag__remove-button)`
`tag__remove-button__base`	The tag's remove button base part.	`::part(tag__remove-button__base)`
`clear-button`	The clear button.	`::part(clear-button)`
`expand-icon`	The container that wraps the expand icon.	`::part(expand-icon)`

Dependencies Jump to heading

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Combobox

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Autocomplete Modes Jump to heading

List Autocomplete (Default) Jump to heading

No Autocomplete Jump to heading

Allow Custom Values Jump to heading

Custom Filter Function Jump to heading

Appearance Jump to heading

Pill Jump to heading

Disabled Jump to heading

Multiple Jump to heading

Setting Initial Values Jump to heading

Grouping Options Jump to heading

Sizes Jump to heading

Placement Jump to heading

Start & End Decorations Jump to heading

Custom Tags Jump to heading

Importing Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Methods Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

Custom States Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Web Awesome Elsewhere

Combobox

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Autocomplete Modes Jump to heading

List Autocomplete (Default) Jump to heading

No Autocomplete Jump to heading

Allow Custom Values Jump to heading

Custom Filter Function Jump to heading

Appearance Jump to heading

Pill Jump to heading

Disabled Jump to heading

Multiple Jump to heading

Setting Initial Values Jump to heading

Grouping Options Jump to heading

Sizes Jump to heading

Placement Jump to heading

Start & End Decorations Jump to heading

Custom Tags Jump to heading

Importing Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Methods Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

Custom States Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

We Have Cookies…