Select
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.
This component works with standard <form> elements. See form controls for form submission and client-side validation.
Examples
Label
Use the label attribute to give the select an accessible label. For labels that contain HTML, use the label slot instead.
Hint
Add a descriptive hint with the hint attribute. For hints that contain HTML, use the hint slot instead.
Placeholder
Use the placeholder attribute to show prompt text before a selection is made.
Appearance
Use the appearance attribute to change the select's visual style.
Pill
Use the pill attribute to give the select rounded edges.
Size
Use the size attribute to change a select's size.
Disabled
Use the disabled attribute to disable a select.
Clearable
Use the with-clear attribute to let people reset their choice. The clear button only appears once an option is selected.
Multiple
To let people choose more than one option, add the multiple attribute. Pair it with with-clear so a long selection is easy to reset. Mark the initial selection with the selected attribute on individual options.
Multiple selections can grow the control vertically.
Use the max-options-visible attribute to cap how many tags show at once before the rest collapse into a count.
Initial Value
Use the selected attribute on individual options to set the initial selection, just like native HTML.
Framework users can bind directly to the value property for reactive data binding and form state management.
Grouping Options
Use <wa-divider> to separate groups of options visually. You can also add <small> labels, but note that most assistive technologies won't announce them.
Placement
Set the placement attribute to control where the listbox opens. Valid placements are bottom (default) and top; the actual position may flip to keep the panel in the viewport.
Start & End Decorations
Use the start and end slots to add presentational elements such as <wa-icon> inside the combobox.
Custom Tags
When multiple options can be selected, supply custom tags by passing a function to the getTag property. The function runs for each selected option and can return a string of HTML, a Lit template, or an HTMLElement. Its first argument is the <wa-option> element and its second is the tag's index.
Because custom tags render in a shadow root, style them with the style attribute in your template, or add your own parts and target them with ::part().
Only pass content you trust to getTag().
Unsanitized user input rendered into a tag can result in XSS vulnerabilities.
When using custom tags with with-remove, include the data-value attribute set to the option's value so the select knows which option to deselect when the tag's remove button is clicked.
Lazy Loading Options
The select handles options that arrive after the initial render, similar to a native <select>:
- Empty select with a value: a
<wa-select>created without options but given avaluestarts with an empty value. When an option whose value matches is added later, the select updates to match. - Multiple select with partial options: a
<wa-select multiple>with an initial value respects only the options present in the DOM. When the remaining selected options load later — and the user hasn't changed the selection — they're added automatically.
Throughout, the select prioritizes user interactions and explicit selections over programmatic changes, keeping behavior predictable even with dynamically loaded content.
API
Importing
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.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/webawesome@3.10.0/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
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
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
appearanceappearance |
The select's visual appearance.
Type
'filled' | 'outlined' | 'filled-outlined'
Default
'outlined'
|
|
disableddisabled |
Disables the select control.
Type
boolean
Default
false
|
|
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
|
|
hinthint |
The select's hint. If you need to display HTML, use the
hint slot instead.
Type
string
Default
''
|
|
labellabel |
The select's label. If you need to display HTML, use the
label slot instead.
Type
string
Default
''
|
|
maxOptionsVisiblemax-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
|
|
multiplemultiple |
Allows more than one option to be selected.
Type
boolean
Default
false
|
|
namename |
The name of the select, submitted as a name/value pair with form data.
Type
string | null
Default
''
|
|
openopen |
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
|
|
pillpill |
Draws a pill-style select with rounded edges.
Type
boolean
Default
false
|
|
placeholderplaceholder |
Placeholder text to show as a hint when the select is empty.
Type
string
Default
''
|
|
placementplacement |
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'
|
|
requiredrequired |
The select's required attribute.
Type
boolean
Default
false
|
|
sizesize |
The select's size.
Type
'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large'
Default
'm'
|
|
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
[]
|
|
valuevalue |
The select's value. This will be a string for single select or an array for multi-select.
|
|
withClearwith-clear |
Adds a clear button when the select is not empty.
Type
boolean
Default
false
|
|
withHintwith-hint |
Only required for SSR. Set to
true if you're slotting in a hint element so the server-rendered markup
includes the hint before the component hydrates on the client.
Type
boolean
Default
false
|
|
withLabelwith-label |
Only required for SSR. Set to
true if you're slotting in a label element so the server-rendered markup
includes the label before the component hydrates on the client.
Type
boolean
Default
false
|
Methods
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
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 select's menu closes and all animations are complete. |
wa-after-show |
Emitted after the select's menu opens and all animations are complete. |
wa-clear |
Emitted when the control's value is cleared. |
wa-hide |
Emitted when the select'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 select's menu opens. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description |
|---|---|
--hide-duration |
The duration of the hide animation.
Default
var(--wa-transition-fast)
|
--show-duration |
The duration of the show animation.
Default
var(--wa-transition-fast)
|
--tag-max-size |
When using
multiple, the max size of tags before their content is truncated.
Default
10ch
|
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
blank |
The select is empty. |
:state(blank)
|
CSS Parts
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 select'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
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.