Combobox

When to Use

Use a Combobox to help users easily search, filter, and select options from long list of options.

Large Datasets

Comboboxes are a better choice than checkbox or radio button groups when dealing with more than 15 options. Unlike static groups that can overwhelm users with lengthy lists, Comboboxes save space and simplify the interface by enabling search and filtering. This makes it easier and faster for users to find their desired option, especially in large datasets like cities, products, or categories, without scrolling through extensive lists.

Multiple Choices

Our combobox comes with multi-selection capabilities that provide a clear overview of selected options by displaying them within a tag list in the input field of the combobox. This is ideal when users need to choose multiple items, as it ensures selections are visible and easy to manage, allowing users to remove or modify choices effortlessly while keeping the interface organized and intuitive.

When Not to Use

Avoid a Combobox when users would benefit more from seeing all options at once for quick selection.

Fully Visible Selection:

For lists with fewer than 5 options and when your interface has plenty of space, choose Checkbox or Radio Button. These components display every option upfront, enabling users to quickly scan and select without extra clicks.

Efficient Selection:

When the options range from 5 to 15 items or when screen space is limited, using a Select component is ideal. It presents all available choices in a concise, accessible format, keeping your UI clean and straightforward. For lists exceeding 15 options, a combobox becomes beneficial by offering search and filtering capabilities to help users navigate a bigger set of choices.

Anatomy

Variants

Combobox comes in two versions, each suited for specific situations:

Single Selection

This variant allows users to choose one option from the list. It’s ideal for scenarios where only one value is required, such as selecting a country or choosing a payment method. Single selection Comboboxes simplify decision-making by focusing the user on one clear choice at a time.

Multiple Selection

Enables users to select more than one option, typically representing choices as chips or stacked labels. This variant is useful in contexts like filters, tagging systems, or multi-category selection, where users need the flexibility to combine options without restriction.

Options

With these options you can tweak the appearance of the combobox in Figma. They are available in the Design Panel so you can compose the button to exactly fit the user experience need for the uses case you are working on.

Combobox Input

Combobox Dropdown

Behaviors

Let's explore the behavior of the Combobox

Grouping Choices

Provides organizational structure for selected items by categorizing them under specific groups or labels. This behavior is especially beneficial in complex datasets where selections belong to distinct categories.

Stacked Selections

Displays multiple selected items as a visually stacked list at the top of the dropdow list or within tag list. This approach keeps the interface tidy and ensures users can quickly review or edit their choices without scrolling through a long dropdown.

Dynamic Filtering

Filters the options list in real time based on user input, displaying only relevant matches. This functionality enhances usability, particularly for lists with many similar or closely related items.

Autocomplete Suggestions

The Combobox provides real-time autocomplete suggestions as users type. This behavior helps narrow down options by displaying only relevant matches, making the selection process faster and more efficient, especially in large datasets. Users can select a suggestion or continue typing to refine their input further.

Related components

• Menu
• Select
• Tag

Listbox

Unlike the native <select> element, you have to wrap the options in an sl-listbox element. This is because the listbox needs to be associated with the <input> element of the embedded text field for accessibility purposes (aria-controls, aria-expanded and aria-haspopup). That can only be done if the listbox is in the same shadow root as the input.

If you are not rendering the options yourself (see below), the combobox component will automatically wrap the options in an sl-listbox element for you.

Options

There are two ways you can define the options for the combobox:

1. By using the sl-option element inside the sl-listbox element yourself
2. By using the options property on the sl-combobox element

There is no difference in behavior of the combobox between the two methods.

Using sl-option elements

Use this method if you have a small to medium number of options and you want to define them directly in your HTML.

<sl-combobox>
  <sl-listbox>
    <sl-option value="0">Mathematics</sl-option>
    <sl-option value="1">Geography</sl-option>
    <sl-option value="2">Physics</sl-option>
    <sl-option value="3">History</sl-option>
  </sl-listbox>
</sl-combobox>

This is usually the simpler method, but it can become a performance issue if you have a large number of options (more than 100 options).

Using the options property

Use this method if you have a large number of options. This method is more performant because it only renders the options that are currently visible. This method can be used with thousands of options, without any degradation in performance (this does not mean you should use the combobox component if you have thousands of options, but there are cases where the amount of options is determined by outside factors).

const options = [
  { value: "0", label: "Mathematics" },
  { value: "1", label: "Geography" },
  { value: "2", label: "Physics" },
  { value: "3", label: "History" }
];

<sl-combobox
  .options=${options}
  option-label-path="label"
  option-value-path="value"
></sl-combobox>

By using the option-group-path, option-label-path, option-selected-path and option-value-path properties, you can specify which properties on the option objects should be used to render the options.

If you only specify a string array as the options property, the combobox will use the strings as both the label and value.

Grouping options

You can group options using the sl-option-group element. This element can contain sl-option elements. It is not recommended to have nested sl-option-group elements.

<sl-combobox>
  <sl-listbox>
    <sl-option-group label="Math">
      <sl-option value="0">Algebra</sl-option>
      <sl-option value="1">Geometry</sl-option>
      <sl-option value="2">Calculus</sl-option>
   </sl-option-group>
    <sl-option-group label="Languages">
      <sl-option value="3">English</sl-option>
      <sl-option value="4">German</sl-option>
      <sl-option value="5">French</sl-option>
      <sl-option value="6">Spanish</sl-option>
      <sl-option value="7">Chinese</sl-option>
    </sl-option-group>
  </sl-listbox>
</sl-combobox>

If you are using the options property, you can group options by setting the option-group-path property. The component will automatically group options based on the value of the specified property. The value of the group property will be used to label the group.

const options = [
  { value: "0", label: "Algebra", group: "Math" },
  { value: "1", label: "Geometry", group: "Math" },
  { value: "2", label: "Calculus", group: "Math" },
  { value: "3", label: "English", group: "Languages" },
  { value: "4", label: "German", group: "Languages" },
  { value: "5", label: "French", group: "Languages" },
  { value: "6", label: "Spanish", group: "Languages" },
  { value: "7", label: "Chinese", group: "Languages" }
];

<sl-combobox
  .options=${options}
  option-group-path="group"
  option-label-path="label"
  option-value-path="value"
></sl-combobox>

Selected

The combobox component is in single selection mode by default. If you want to enable multiple selection, you can set the multiple property on the sl-combobox element. The value property is, depending on the selection mode, either a single value or an array of values.

There are two ways you can set the selected options for the combobox:

1. By using the value property on the sl-combobox element
2. By using the selected property on the sl-option elements

It is sometimes easier to set the selected property since you are already rendering the options yourself. If you are not rendering the options yourself, you can specify the group-selected-path property instead.

In both cases you could also use the value property on the sl-combobox element to set the selected options.

Do not use both methods at the same time.

API

The Combobox streamlines single and multiple selections in large datasets of over 15 options. Its autocomplete feature filters options as users type, improving speed and usability. For multiple selections, it displays choices as tags in a tag list, enabling easy management and clear visibility of selected items.

Properties

Methods

Events

Slots

Keyboard interactions

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a combobox component provide essential information to assistive technologies and screen readers. They convey the combobox component's role, and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.

Input

Listbox