Combobox

<wa-combobox>

Since 2.0

stable

A combobox lets you select an item from a list of dynamically retrieved options. You can also type in the field to quickly filter the list.

<wa-combobox class="combobox-remote"
  clearable>
</wa-combobox>

<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

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.

<wa-combobox label="Select one"  class="combobox-remote">
</wa-combobox>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Hint Jump to heading

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

                
  Novice
  Intermediate
  Advanced

<wa-combobox label="Experience" hint="Please tell us your skill level."  class="combobox-remote">
  <wa-option value="1">Novice</wa-option>
  <wa-option value="2">Intermediate</wa-option>
  <wa-option value="3">Advanced</wa-option>
</wa-combobox>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Placeholders Jump to heading

Use the placeholder attribute to add a placeholder.

                
  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Select one" class="combobox-remote">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Clearable Jump to heading

Use the with-clear attribute to make the control clearable. The clear button only appears when an option is selected.

                
  Option 1
  Option 2
  Option 3

<wa-combobox with-clear value="option-1" class="combobox-remote" placement="top">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Appearance Jump to heading

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

                
  Option 1
  Option 2
  Option 3

<wa-combobox appearance="filled" class="combobox-remote">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Pill Jump to heading

Use the pill attribute to give comboboxes rounded edges.

                
  Option 1
  Option 2
  Option 3

<wa-combobox pill class="combobox-remote">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

Disabled Jump to heading

Use the disabled attribute to disable a combobox.

                
  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Disabled" disabled class="combobox-remote">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

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 class="combobox-remote">
  <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>
<script>
  const combobox = document.querySelector('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  combobox.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
</script>

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

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>

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">
  <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.

                
  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

  Option 1
  Option 2
  Option 3

<wa-combobox placeholder="Small" size="small" with-clear>
  <wa-icon slot="start" name="house" variant="solid"></wa-icon>
  <wa-icon slot="end" name="flag-checkered"></wa-icon>
  <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" with-clear>
  <wa-icon slot="start" name="house" variant="solid"></wa-icon>
  <wa-icon slot="end" name="flag-checkered"></wa-icon>
  <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" with-clear>
  <wa-icon slot="start" name="house" variant="solid"></wa-icon>
  <wa-icon slot="end" name="flag-checkered"></wa-icon>
  <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>


<script>
  const comboboxes = document.querySelectorAll('.combobox-remote');
  const url = 'https://60db3b45801dcb0017290fdb.mockapi.io/users?name={q}';
  comboboxes.forEach((v)=>{
      v.source = search => {
    return fetch(url.replace('{q}', search))
      .then(res => res.json())
      .then(data =>
        data.map(d => {
          return {
            text: d.name,
            value: d.id
          };
        })
      );
    };
  })
</script>

The key principle is that the combobox component prioritizes user interactions and explicit selections over programmatic changes, ensuring a predictable user experience even with dynamically loaded content.

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
`name` `name`	The name of the select, submitted as a name/value pair with form data. Type `string` Default `''`
`value` `value`	The select's value. This will be a string for single select or an array for multi-select.
`size` `size`	The select's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`placeholder` `placeholder`	Placeholder text to show as a hint when the select is empty. Type `string` Default `''`
`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 select control. Type `boolean` Default `false`
`withClear` `with-clear`	Adds a clear button when the select is not empty. Type `boolean` Default `false`
`open` `open`	Indicates whether or not the select 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 select's open state. Type `boolean` Default `false`
`appearance` `appearance`	The select's visual appearance. Type `'filled' \| 'outlined'` Default `'outlined'`
`pill` `pill`	Draws a pill-style select with rounded edges. Type `boolean` Default `false`
`label` `label`	The select's label. If you need to display HTML, use the `label` slot instead. Type `string` Default `''`
`placement` `placement`	The preferred placement of the select'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 select'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`
`form` `form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type `null` Default `null`
`required` `required`	The select's required attribute. Type `boolean` Default `false`
`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`
`source` `source`	The source property is a function executed on user input. The search result is displayed in the suggestions list. Type `SuggestionSource \| undefined`
`emptyMessage` `empty-message`	Message displayed when no result found. Type `string` Default `'no data found'`

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
`--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)`

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description
`form-control`	The form control that wraps the label, input, and hint.
`form-control-label`	The label's wrapper.
`form-control-input`	The combobox's wrapper.
`hint`	The hint's wrapper.
`combobox`	The container the wraps the start, end, value, clear icon, and expand button.
`start`	The container that wraps the `start` slot.
`end`	The container that wraps the `end` slot.
`display-input`	The element that displays the selected option's label, an `<input>` element.
`listbox`	The listbox container where options are slotted.
`tags`	The container that houses option tags when `multiselect` is used.
`tag`	The individual tags that represent each multiselect option.
`tag__content`	The tag's content part.
`tag__remove-button`	The tag's remove button.
`tag__remove-button__base`	The tag's remove button base part.
`clear-button`	The clear button.
`expand-icon`	The container that wraps the 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.

Importing Jump to heading

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

CDN

npm

React

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

import 'https://early.webawesome.com/webawesome@0.5.1/dist/components/combobox/combobox.js';

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';

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Combobox

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Appearance Jump to heading

Pill Jump to heading

Disabled Jump to heading

Setting Initial Values Jump to heading

Sizes Jump to heading

Placement Jump to heading

Start & End Decorations 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

Importing Jump to heading

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Combobox

Examples Jump to heading #

Labels Jump to heading #

Hint Jump to heading #

Placeholders Jump to heading #

Clearable Jump to heading #

Appearance Jump to heading #

Pill Jump to heading #

Disabled Jump to heading #

Setting Initial Values Jump to heading #

Sizes Jump to heading #

Placement Jump to heading #

Start & End Decorations 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 #

Importing Jump to heading #

Examples Jump to heading

Labels Jump to heading

Hint Jump to heading

Placeholders Jump to heading

Clearable Jump to heading

Appearance Jump to heading

Pill Jump to heading

Disabled Jump to heading

Setting Initial Values Jump to heading

Sizes Jump to heading

Placement Jump to heading

Start & End Decorations 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

Importing Jump to heading