Select

<wa-select> Stable Since 2.0

Selects let users choose one or more values from a dropdown list of predefined options. Use them in forms when a fixed set of choices needs to fit in limited space.

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

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 select an accessible label. For labels that contain HTML, use the label slot instead.

Option 1 Option 2 Option 3

Hint

Link to This Section

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

Novice Intermediate Advanced

Placeholders

Link to This Section

Use the placeholder attribute to add a placeholder.

Option 1 Option 2 Option 3

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

Appearance

Link to This Section

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

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3

Pill

Link to This Section

Use the pill attribute to give selects rounded edges.

Option 1 Option 2 Option 3

Disabled

Link to This Section

Use the disabled attribute to disable a select.

Option 1 Option 2 Option 3

Multiple

Link to This Section

To allow multiple options to be selected, use the multiple attribute. It's a good practice to use with-clear when this option is enabled. You can select multiple options by adding the selected attribute to individual options.

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

Selecting multiple options may result in wrapping, causing the control to expand vertically. You can use the max-options-visible attribute to control the maximum number of selected options to show at once.

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

For multiple selections, apply it to all selected options.

Option 1 Option 2 Option 3 Option 4

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

Grouping Options

Link to This Section

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.

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

Sizes

Link to This Section

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

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3

Placement

Link to This Section

The preferred placement of the select'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

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
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3

Custom Tags

Link to This Section

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

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.

Lazy loading options

Link to This Section

Lazy loading options works similarly to native <select> elements. The select component handles various scenarios intelligently:

Basic lazy loading scenarios:

Link to This Section

Here's a comprehensive example showing different lazy loading scenarios:

Bar Baz
Add "foo" option


Add "foo" option

Bar Baz
Add "foo" option (selected)


Add "foo" option


Reset Show FormData


The key principle is that the select 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/[email protected]/components/select/select.js';

After installing Web Awesome via npm, import this component:

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

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

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

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

import WaSelect from '@awesome.me/webawesome/dist/react/select/index.js';

Slots

Link to This Section

Learn more about using slots.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Methods

Link to This Section

Learn more about methods.

Events

Link to This Section

Learn more about events.

CSS custom properties

Link to This Section

Learn more about CSS custom properties.

Custom States

Link to This Section

Learn more about custom states.

CSS parts

Link to This Section

Learn more about CSS parts.

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
    No results