Combobox

<wa-combobox>

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

Link to This Section

Labels

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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

Link to This Section

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>

Custom Value

Link to This Section

Use the custom-value attribute to allow users to enter values that aren't in the suggestions list. The typed value is committed when the user presses Enter or moves focus away from the combobox.

Current value: —

<wa-combobox
  label="Reason for completion"
  placeholder="Select or type a reason"
  custom-value
  class="combobox-custom-value"
></wa-combobox>

<div style="margin-top: 0.75rem; font-size: 0.875rem; color: var(--wa-color-neutral-600)">
  Current value: <strong id="custom-value-output">—</strong>
</div>

<script>
  const combobox = document.querySelector('.combobox-custom-value');
  const output = document.querySelector('#custom-value-output');

  combobox.source = query => {
    const options = [
      { value: 'Target depth reached', text: 'Target depth reached' },
      { value: 'Equipment failure', text: 'Equipment failure' },
      { value: 'Obstruction encountered', text: 'Obstruction encountered' },
    ];
    if (!query) return options;
    return options.filter(o => o.text.toLowerCase().includes(query.toLowerCase()));
  };

  combobox.addEventListener('change', () => {
    output.textContent = combobox.value || '—';
  });
</script>

Start & End Decorations

Link to This Section

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.

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN

npm

Self-Hosted

React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/webawesome@0.17.0/components/combobox/combobox.js';

After installing Web Awesome via npm, import this component:

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

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/combobox/combobox.js';

To import this component for React 18 or below, use the following code:

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

Slots

Link to This Section

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.
`clear-icon`	An icon to use in lieu of the default clear icon.
`end`	An element, such as `<wa-icon>`, placed at the end of the combobox.
`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.
`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.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name	Description	Reflects
`appearance` `appearance`	The select's visual appearance. Type `'filled' \| 'outlined'` Default `'outlined'`
`customValue` `custom-value`	When true, allows the user to enter a custom value that is not in the list of options. Type `boolean` Default `false`
`disabled` `disabled`	Disables the select control. Type `boolean` Default `false`
`emptyMessage` `empty-message`	Message displayed when no result found. Type `string` Default `'no data found'`
`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 `HTMLFormElement \| 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`
`hint` `hint`	The select's hint. If you need to display HTML, use the `hint` slot instead. Type `string` Default `''`
`label` `label`	The select's label. If you need to display HTML, use the `label` slot instead. 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`
`name` `name`	The name of the select, submitted as a name/value pair with form data. Type `string \| null` Default `''`
`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`
`pill` `pill`	Draws a pill-style select with rounded edges. Type `boolean` Default `false`
`placeholder` `placeholder`	Placeholder text to show as a hint when the select is empty. 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'`
`required` `required`	The select's required attribute. Type `boolean` Default `false`
`size` `size`	The select's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`source` `source`	The source property is a function executed on user input. The search result is displayed in the suggestions list. Type `SuggestionSource \| undefined`
`validationTarget`	Where to anchor native constraint validation Type `undefined \| HTMLElement`
`validators`	Validators are static because they have `observedAttributes`, essentially attributes to "watch" for changes. Whenever these attributes change, we want to be notified and update the validator. Type `Validator[]` Default `[]`
`value` `value`	The select's value. This will be a string for single select or an array for multi-select.
`withClear` `with-clear`	Adds a clear button when the select is not empty. 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`
`withLabel` `with-label`	Used for SSR purposes when a label is slotted in. Will show the label on first render. Type `boolean` Default `false`

Methods

Link to This Section

Learn more about methods.

Name	Description	Arguments
`blur()`	Removes focus from the control.
`focus()`	Sets focus on the control.	`options: FocusOptions`
`formStateRestoreCallback()`	Called when the browser is trying to restore element’s state to state in which case reason is "restore", or when the browser is trying to fulfill autofill on behalf of user in which case reason is "autocomplete". In the case of "restore", state is a string, File, or FormData object previously set as the second argument to setFormValue.	`state: string \| File \| FormData \| null, reason: 'autocomplete' \| 'restore'`
`hide()`	Hides the listbox.
`resetValidity()`	Reset validity is a way of removing manual custom errors and native validation.
`setCustomValidity()`	Do not use this when creating a "Validator". This is intended for end users of components. We track manually defined custom errors so we don't clear them on accident in our validators.	`message: string`
`show()`	Shows the listbox.

Events

Link to This Section

Learn more about events.

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

CSS Custom Properties

Link to This Section

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

Link to This Section

Learn more about custom states.

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

CSS Parts

Link to This Section

Learn more about CSS parts.

Name	Description	CSS selector
`clear-button`	The clear button.	`::part(clear-button)`
`combobox`	The container the wraps the start, end, value, clear icon, and expand button.	`::part(combobox)`
`display-input`	The element that displays the selected option's label, an `<input>` element.	`::part(display-input)`
`end`	The container that wraps the `end` slot.	`::part(end)`
`expand-icon`	The container that wraps the expand icon.	`::part(expand-icon)`
`form-control`	The form control that wraps the label, input, and hint.	`::part(form-control)`
`form-control-input`	The combobox's wrapper.	`::part(form-control-input)`
`form-control-label`	The label's wrapper.	`::part(form-control-label)`
`hint`	The hint's wrapper.	`::part(hint)`
`listbox`	The listbox container where options are slotted.	`::part(listbox)`
`start`	The container that wraps the `start` slot.	`::part(start)`
`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)`
`tags`	The container that houses option tags when `multiselect` is used.	`::part(tags)`

Dependencies

Link to This Section

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

Combobox

Examples

Labels

Hint

Placeholders

Clearable

Appearance

Pill

Disabled

Setting Initial Values

Sizes

Placement

Custom Value

Start & End Decorations

Importing

Slots

Attributes & Properties

Methods

Events

CSS Custom Properties

Custom States

CSS Parts

Dependencies

Quick Links

Recent Searches