Combobox
Examples
Remote source for suggestions
Default Value
Local source for suggestions
Importing
Properties
Events
Parts
Dependencies

Combobox

<sl-combobox> | SlCombobox

since ViUR 0.5

stable

The sl-combobox component provides suggestions while users type into the search field. This is very useful when you need to quickly find and select an item from a list of values.

<sl-combobox
  clearable
>
  <sl-icon name="search" slot="suffix"></sl-icon>
</sl-combobox>

<script>
  const combobox = document.querySelector('sl-combobox');
  
  const countries = ["Afghanistan","Albania","Algeria","Andorra","Angola","Anguilla","Antigua & Barbuda","Argentina","Armenia","Aruba","Australia","Austria","Azerbaijan","Bahamas","Bahrain","Bangladesh","Barbados","Belarus","Belgium","Belize","Benin","Bermuda","Bhutan","Bolivia","Bosnia & Herzegovina","Botswana","Brazil","British Virgin Islands","Brunei","Bulgaria","Burkina Faso","Burundi","Cambodia","Cameroon","Canada","Cape Verde","Cayman Islands","Central Arfrican Republic","Chad","Chile","China","Colombia","Congo","Cook Islands","Costa Rica","Cote D Ivoire","Croatia","Cuba","Curacao","Cyprus","Czech Republic","Denmark","Djibouti","Dominica","Dominican Republic","Ecuador","Egypt","El Salvador","Equatorial Guinea","Eritrea","Estonia","Ethiopia","Falkland Islands","Faroe Islands","Fiji","Finland","France","French Polynesia","French West Indies","Gabon","Gambia","Georgia","Germany","Ghana","Gibraltar","Greece","Greenland","Grenada","Guam","Guatemala","Guernsey","Guinea","Guinea Bissau","Guyana","Haiti","Honduras","Hong Kong","Hungary","Iceland","India","Indonesia","Iran","Iraq","Ireland","Isle of Man","Israel","Italy","Jamaica","Japan","Jersey","Jordan","Kazakhstan","Kenya","Kiribati","Kosovo","Kuwait","Kyrgyzstan","Laos","Latvia","Lebanon","Lesotho","Liberia","Libya","Liechtenstein","Lithuania","Luxembourg","Macau","Macedonia","Madagascar","Malawi","Malaysia","Maldives","Mali","Malta","Marshall Islands","Mauritania","Mauritius","Mexico","Micronesia","Moldova","Monaco","Mongolia","Montenegro","Montserrat","Morocco","Mozambique","Myanmar","Namibia","Nauro","Nepal","Netherlands","Netherlands Antilles","New Caledonia","New Zealand","Nicaragua","Niger","Nigeria","North Korea","Norway","Oman","Pakistan","Palau","Palestine","Panama","Papua New Guinea","Paraguay","Peru","Philippines","Poland","Portugal","Puerto Rico","Qatar","Reunion","Romania","Russia","Rwanda","Saint Pierre & Miquelon","Samoa","San Marino","Sao Tome and Principe","Saudi Arabia","Senegal","Serbia","Seychelles","Sierra Leone","Singapore","Slovakia","Slovenia","Solomon Islands","Somalia","South Africa","South Korea","South Sudan","Spain","Sri Lanka","St Kitts & Nevis","St Lucia","St Vincent","Sudan","Suriname","Swaziland","Sweden","Switzerland","Syria","Taiwan","Tajikistan","Tanzania","Thailand","Timor L'Este","Togo","Tonga","Trinidad & Tobago","Tunisia","Turkey","Turkmenistan","Turks & Caicos","Tuvalu","Uganda","Ukraine","United Arab Emirates","United Kingdom","United States of America","Uruguay","Uzbekistan","Vanuatu","Vatican City","Venezuela","Vietnam","Virgin Islands (US)","Yemen","Zambia","Zimbabwe"];

  combobox.source = async (search) => {
      let filter = countries.filter(name => 
        name.toLowerCase()
          .includes(search.toLowerCase())
      )
        .slice(0, 20);

      return filter.map(d => { return { text: d, value: d } });
  };
</script>

Examples

Remote source for suggestions

You can define a remote source to retrieve a list of data.

<sl-combobox
  class="combobox-remote"
  clearable>
</sl-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>

Default Value

The sl-combobox component also works with local data.

<sl-combobox id="default" value="Bahamas"
  clearable>
</sl-combobox>

<script>
  const combobox = document.querySelector('sl-combobox#default');
  
  const countries = ["Afghanistan","Albania","Algeria","Andorra","Angola","Anguilla","Antigua & Barbuda","Argentina","Armenia","Aruba","Australia","Austria","Azerbaijan","Bahamas","Bahrain","Bangladesh","Barbados","Belarus","Belgium","Belize","Benin","Bermuda","Bhutan","Bolivia","Bosnia & Herzegovina","Botswana","Brazil","British Virgin Islands","Brunei","Bulgaria","Burkina Faso","Burundi","Cambodia","Cameroon","Canada","Cape Verde","Cayman Islands","Central Arfrican Republic","Chad","Chile","China","Colombia","Congo","Cook Islands","Costa Rica","Cote D Ivoire","Croatia","Cuba","Curacao","Cyprus","Czech Republic","Denmark","Djibouti","Dominica","Dominican Republic","Ecuador","Egypt","El Salvador","Equatorial Guinea","Eritrea","Estonia","Ethiopia","Falkland Islands","Faroe Islands","Fiji","Finland","France","French Polynesia","French West Indies","Gabon","Gambia","Georgia","Germany","Ghana","Gibraltar","Greece","Greenland","Grenada","Guam","Guatemala","Guernsey","Guinea","Guinea Bissau","Guyana","Haiti","Honduras","Hong Kong","Hungary","Iceland","India","Indonesia","Iran","Iraq","Ireland","Isle of Man","Israel","Italy","Jamaica","Japan","Jersey","Jordan","Kazakhstan","Kenya","Kiribati","Kosovo","Kuwait","Kyrgyzstan","Laos","Latvia","Lebanon","Lesotho","Liberia","Libya","Liechtenstein","Lithuania","Luxembourg","Macau","Macedonia","Madagascar","Malawi","Malaysia","Maldives","Mali","Malta","Marshall Islands","Mauritania","Mauritius","Mexico","Micronesia","Moldova","Monaco","Mongolia","Montenegro","Montserrat","Morocco","Mozambique","Myanmar","Namibia","Nauro","Nepal","Netherlands","Netherlands Antilles","New Caledonia","New Zealand","Nicaragua","Niger","Nigeria","North Korea","Norway","Oman","Pakistan","Palau","Palestine","Panama","Papua New Guinea","Paraguay","Peru","Philippines","Poland","Portugal","Puerto Rico","Qatar","Reunion","Romania","Russia","Rwanda","Saint Pierre & Miquelon","Samoa","San Marino","Sao Tome and Principe","Saudi Arabia","Senegal","Serbia","Seychelles","Sierra Leone","Singapore","Slovakia","Slovenia","Solomon Islands","Somalia","South Africa","South Korea","South Sudan","Spain","Sri Lanka","St Kitts & Nevis","St Lucia","St Vincent","Sudan","Suriname","Swaziland","Sweden","Switzerland","Syria","Taiwan","Tajikistan","Tanzania","Thailand","Timor L'Este","Togo","Tonga","Trinidad & Tobago","Tunisia","Turkey","Turkmenistan","Turks & Caicos","Tuvalu","Uganda","Ukraine","United Arab Emirates","United Kingdom","United States of America","Uruguay","Uzbekistan","Vanuatu","Vatican City","Venezuela","Vietnam","Virgin Islands (US)","Yemen","Zambia","Zimbabwe"];

  combobox.source = async (search) => {
      let filter = countries.filter(name => 
        name.toLowerCase()
          .includes(search.toLowerCase())
      )
        .slice(0, 20);

      return filter.map(d => { return { text: d, value: d } });
  };
</script>

Local source for suggestions

The sl-combobox component also works with local data.

<sl-combobox id="local"
  clearable>
</sl-combobox>

<script>
  const combobox = document.querySelector('sl-combobox#local');
  
  const countries = ["Afghanistan","Albania","Algeria","Andorra","Angola","Anguilla","Antigua & Barbuda","Argentina","Armenia","Aruba","Australia","Austria","Azerbaijan","Bahamas","Bahrain","Bangladesh","Barbados","Belarus","Belgium","Belize","Benin","Bermuda","Bhutan","Bolivia","Bosnia & Herzegovina","Botswana","Brazil","British Virgin Islands","Brunei","Bulgaria","Burkina Faso","Burundi","Cambodia","Cameroon","Canada","Cape Verde","Cayman Islands","Central Arfrican Republic","Chad","Chile","China","Colombia","Congo","Cook Islands","Costa Rica","Cote D Ivoire","Croatia","Cuba","Curacao","Cyprus","Czech Republic","Denmark","Djibouti","Dominica","Dominican Republic","Ecuador","Egypt","El Salvador","Equatorial Guinea","Eritrea","Estonia","Ethiopia","Falkland Islands","Faroe Islands","Fiji","Finland","France","French Polynesia","French West Indies","Gabon","Gambia","Georgia","Germany","Ghana","Gibraltar","Greece","Greenland","Grenada","Guam","Guatemala","Guernsey","Guinea","Guinea Bissau","Guyana","Haiti","Honduras","Hong Kong","Hungary","Iceland","India","Indonesia","Iran","Iraq","Ireland","Isle of Man","Israel","Italy","Jamaica","Japan","Jersey","Jordan","Kazakhstan","Kenya","Kiribati","Kosovo","Kuwait","Kyrgyzstan","Laos","Latvia","Lebanon","Lesotho","Liberia","Libya","Liechtenstein","Lithuania","Luxembourg","Macau","Macedonia","Madagascar","Malawi","Malaysia","Maldives","Mali","Malta","Marshall Islands","Mauritania","Mauritius","Mexico","Micronesia","Moldova","Monaco","Mongolia","Montenegro","Montserrat","Morocco","Mozambique","Myanmar","Namibia","Nauro","Nepal","Netherlands","Netherlands Antilles","New Caledonia","New Zealand","Nicaragua","Niger","Nigeria","North Korea","Norway","Oman","Pakistan","Palau","Palestine","Panama","Papua New Guinea","Paraguay","Peru","Philippines","Poland","Portugal","Puerto Rico","Qatar","Reunion","Romania","Russia","Rwanda","Saint Pierre & Miquelon","Samoa","San Marino","Sao Tome and Principe","Saudi Arabia","Senegal","Serbia","Seychelles","Sierra Leone","Singapore","Slovakia","Slovenia","Solomon Islands","Somalia","South Africa","South Korea","South Sudan","Spain","Sri Lanka","St Kitts & Nevis","St Lucia","St Vincent","Sudan","Suriname","Swaziland","Sweden","Switzerland","Syria","Taiwan","Tajikistan","Tanzania","Thailand","Timor L'Este","Togo","Tonga","Trinidad & Tobago","Tunisia","Turkey","Turkmenistan","Turks & Caicos","Tuvalu","Uganda","Ukraine","United Arab Emirates","United Kingdom","United States of America","Uruguay","Uzbekistan","Vanuatu","Vatican City","Venezuela","Vietnam","Virgin Islands (US)","Yemen","Zambia","Zimbabwe"];

  combobox.source = async (search) => {
      let filter = countries.filter(name => 
        name.toLowerCase()
          .includes(search.toLowerCase())
      )
        .slice(0, 20);

      return filter.map(d => { return { text: d, value: d } });
  };
</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script

Import

Bundler

React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@viur/shoelace@1.0.8-v2.19.1/cdn/components/combobox/combobox.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@viur/shoelace@1.0.8-v2.19.1/cdn/components/combobox/combobox.js';

To import this component using a bundler:

import '@viur/shoelace/dist/components/combobox/combobox.js';

To import this component as a React component:

import SlCombobox from '@viur/shoelace/dist/react/combobox';

Properties

Name	Description	Type	Default
`value`	The current input	`string`	`''`
`size`	The combobox’s size.	`'small' \| 'medium' \| 'large'`	`'medium'`
`pill`	Draws a pill-style combobox with rounded edges.	`boolean`	`false`
`label`	The combobox’s label.	`string`	-
`name`	The combobox’s name attribute.	`string`	-
`helpText` `help-text`	The combobox’s help text.	`string`	`''`
`clearable`	Adds a clear button when the input is populated.	`boolean`	`false`
`hoist`	Enable this option to prevent the panel from being clipped when the component is placed inside a container with `overflow: auto\|scroll`.	`boolean`	`false`
`placeholder`	The input’s placeholder text.	`string`	-
`autofocus`	The input’s autofocus attribute.	`boolean`	-
`disabled`	Disables the combobox component.	`boolean`	`false`
`emptyMessage` `empty-message`	Message displayed when no result found.	`string`	`'no data found'`
`source`	The source property is a function executed on user input. The search result is displayed in the suggestions list.	`SuggestionSource \| undefined`	-
`openEmpty`	If true the suggestions are shown even if the Input is empty	`boolean`	`false`
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	React Event	Description	Event Detail
`sl-item-select`	`onSlItemSelect`	DEPRECATED - Emitted when a suggestion is selected.	`{ item: SlMenuItem }`
`sl-select`	`onSlSelect`	Emitted when a suggestion is selected.	`{ item: SlMenuItem }`
`sl-change`	`onSlChange`	Emitted when the input’s value changes.	-
`sl-input`	`onSlInput`	Emitted when the input receives input.	-

Learn more about events.

Parts

Name	Description
`base`	The component’s base wrapper, a sl-dropdown.
`input`	The sl-input component.
`menu`	The sl-menu component.
`menu-item`	The sl-menu-item component.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<sl-dropdown>
<sl-icon>
<sl-input>
<sl-menu>
<sl-menu-item>
<sl-popup>
<sl-spinner>