Font Awesome Build Awesome
Try SSR Server-side rendering (SSR) generates component HTML on the server before the page loads, improving SEO and initial load time. Use the switch to see Web Awesome components render with and without SSR.
Search this website ⌘KCtrl+K Light Dark System Docs Select Color Scheme Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Select Theme View Project on GitHub Star Project on GitHub
Start Components Docs Help
Web Awesome Font Awesome Build Awesome
Search this site… /
Try SSR Server-side rendering (SSR) generates component HTML on the server before the page loads, improving SEO and initial load time. Use the switch to see Web Awesome components render with and without SSR.
Light Dark System Docs Select Color Scheme Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Select Theme

Getting Started

  • Installation
  • Usage
  • Forms
  • Localization
  • Frameworks
  • Using with AI
  • Figma Design Kit ProThis requires access to Web Awesome Pro
  • Server Rendering

Resources

  • Accessibility
  • Browser Support
  • Contributing
  • Patterns ProPatterns require access to Web Awesome Pro
  • Migrating from Shoelace
  • Visual Tests
  • Changelog
  • Help & Support

Theming & Utilities

  • Overview
  • Built-in Themes
  • Color Palettes
  • Design Tokens
  • Customizing & Theming
  • CSS Utilities

Actions

  • Button
  • Button Group
  • Copy Button
  • Dropdown
    • Dropdown Item

Forms

  • Checkbox
  • Checkbox Group
  • Color Picker
  • Input
  • Known Date
  • Number Input
  • Radio Group
    • Radio
  • Rating
  • Select
    • Option
  • Slider
  • Switch
  • Textarea
  • Time Input
  • Data Grid Planned A Web Awesome Kickstarter stretch goal!

Layout

  • Accordion
    • Accordion Item
  • Card
  • Details
  • Dialog
  • Divider
  • Drawer
  • Page
  • Scroller
  • Split Panel

Navigation

  • Breadcrumb
    • Breadcrumb Item
  • Tab Group
    • Tab
    • Tab Panel
  • Tree
    • Tree Item

Feedback

  • Badge
  • Callout
  • Progress Bar
  • Progress Ring
  • Skeleton
  • Spinner
  • Tag
  • Tooltip

Media

  • Animated Image
  • Avatar
  • Carousel
    • Carousel Item
  • Comparison
  • Icon
  • Markdown
  • QR Code
  • Zoomable Frame

Data Viz

  • Advanced Usage

Helpers

  • Animation
  • Format Bytes
  • Format Date
  • Format Number
  • Include
  • Intersection Observer
  • Mutation Observer
  • Popover
  • Popup
  • Random Content
  • Relative Time
  • Resize Observer

Select

  • Examples
  • Label
  • Hint
  • Placeholder
  • Appearance
  • Pill
  • Size
  • Disabled
  • Clearable
  • Multiple
  • Initial Value
  • Grouping Options
  • Placement
  • Start & End Decorations
  • Custom Tags
  • Lazy Loading Options
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies
On This Page...
  • Examples
  • Label
  • Hint
  • Placeholder
  • Appearance
  • Pill
  • Size
  • Disabled
  • Clearable
  • Multiple
  • Initial Value
  • Grouping Options
  • Placement
  • Start & End Decorations
  • Custom Tags
  • Lazy Loading Options
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies

Select

<wa-select>
Stable Forms 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.

Espresso Latte Cappuccino Cold brew Drip
<wa-select label="Coffee order" placeholder="How do you take it?">
  <wa-option value="espresso">Espresso</wa-option>
  <wa-option value="latte">Latte</wa-option>
  <wa-option value="cappuccino">Cappuccino</wa-option>
  <wa-option value="cold-brew">Cold brew</wa-option>
  <wa-option value="drip">Drip</wa-option>
</wa-select>

This component works with standard <form> elements. See form controls for form submission and client-side validation.

Examples

Link to This Section

Label

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.

United States Canada Mexico
<wa-select label="Country">
  <wa-option value="us">United States</wa-option>
  <wa-option value="ca">Canada</wa-option>
  <wa-option value="mx">Mexico</wa-option>
</wa-select>

Hint

Link to This Section

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

Novice Intermediate Advanced
<wa-select label="Experience" hint="Tell us how comfortable you are with the command line.">
  <wa-option value="1">Novice</wa-option>
  <wa-option value="2">Intermediate</wa-option>
  <wa-option value="3">Advanced</wa-option>
</wa-select>

Placeholder

Link to This Section

Use the placeholder attribute to show prompt text before a selection is made.

Option 1 Option 2 Option 3
<wa-select placeholder="Select one">
  <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-select>

Appearance

Link to This Section

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

outlined filled filled-outlined
<div class="wa-stack">
  <wa-select appearance="outlined" value="outlined">
    <wa-option value="outlined">outlined</wa-option>
  </wa-select>
  <wa-select appearance="filled" value="filled">
    <wa-option value="filled">filled</wa-option>
  </wa-select>
  <wa-select appearance="filled-outlined" value="filled-outlined">
    <wa-option value="filled-outlined">filled-outlined</wa-option>
  </wa-select>
</div>

Pill

Link to This Section

Use the pill attribute to give the select rounded edges.

Option 1 Option 2 Option 3
<wa-select pill placeholder="Select one">
  <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-select>

Size

Link to This Section

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

Option 1 Option 2 Option 1 Option 2 Option 1 Option 2 Option 1 Option 2 Option 1 Option 2
<div class="wa-stack">
  <wa-select size="xs" placeholder="Extra small">
    <wa-option value="option-1">Option 1</wa-option>
    <wa-option value="option-2">Option 2</wa-option>
  </wa-select>
  <wa-select size="s" placeholder="Small">
    <wa-option value="option-1">Option 1</wa-option>
    <wa-option value="option-2">Option 2</wa-option>
  </wa-select>
  <wa-select size="m" placeholder="Medium">
    <wa-option value="option-1">Option 1</wa-option>
    <wa-option value="option-2">Option 2</wa-option>
  </wa-select>
  <wa-select size="l" placeholder="Large">
    <wa-option value="option-1">Option 1</wa-option>
    <wa-option value="option-2">Option 2</wa-option>
  </wa-select>
  <wa-select size="xl" placeholder="Extra large">
    <wa-option value="option-1">Option 1</wa-option>
    <wa-option value="option-2">Option 2</wa-option>
  </wa-select>
</div>

Disabled

Link to This Section

Use the disabled attribute to disable a select.

Option 1 Option 2 Option 3
<wa-select placeholder="Disabled" disabled>
  <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-select>

Clearable

Link to This Section

Use the with-clear attribute to let people reset their choice. The clear button only appears once an option is selected.

Option 1 Option 2 Option 3
<wa-select with-clear value="option-1">
  <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-select>

Multiple

Link to This Section

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.

Mentions Replies Reactions New followers Releases
<wa-select label="Notify me about" multiple with-clear>
  <wa-option value="mentions" selected>Mentions</wa-option>
  <wa-option value="replies" selected>Replies</wa-option>
  <wa-option value="reactions">Reactions</wa-option>
  <wa-option value="follows">New followers</wa-option>
  <wa-option value="releases">Releases</wa-option>
</wa-select>

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

Link to This Section

Use the selected attribute on individual options to set the initial selection, just like native HTML.

main develop staging
<wa-select label="Default branch">
  <wa-option value="main" selected>main</wa-option>
  <wa-option value="develop">develop</wa-option>
  <wa-option value="staging">staging</wa-option>
</wa-select>

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 separate groups of options visually. You can also add <small> labels, but note that most assistive technologies won't announce them.

Frontend TypeScript CSS Backend Go Rust Python
<wa-select label="Add a language" placeholder="Select one">
  <small>Frontend</small>
  <wa-option value="ts">TypeScript</wa-option>
  <wa-option value="css">CSS</wa-option>
  <wa-divider></wa-divider>
  <small>Backend</small>
  <wa-option value="go">Go</wa-option>
  <wa-option value="rust">Rust</wa-option>
  <wa-option value="python">Python</wa-option>
</wa-select>

Placement

Link to This Section

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.

Option 1 Option 2 Option 3
<wa-select placement="top" placeholder="Opens upward">
  <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-select>

Start & End Decorations

Link to This Section

Use the start and end slots to add presentational elements such as <wa-icon> inside the combobox.

Los Angeles New York Tokyo
<wa-select label="Destination" placeholder="Where to?" with-clear>
  <wa-icon slot="start" name="plane-departure" variant="solid"></wa-icon>
  <wa-option value="lax">Los Angeles</wa-option>
  <wa-option value="jfk">New York</wa-option>
  <wa-option value="nrt">Tokyo</wa-option>
</wa-select>

Custom Tags

Link to This Section

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().

Email Phone Chat
<wa-select placeholder="Select one" multiple with-clear class="custom-tag">
  <wa-option value="email" selected>
    <wa-icon slot="start" name="envelope" variant="solid"></wa-icon>
    Email
  </wa-option>
  <wa-option value="phone" selected>
    <wa-icon slot="start" name="phone" variant="solid"></wa-icon>
    Phone
  </wa-option>
  <wa-option value="chat">
    <wa-icon slot="start" name="comment" variant="solid"></wa-icon>
    Chat
  </wa-option>
</wa-select>

<script type="module">
  await customElements.whenDefined('wa-select');
  const select = document.querySelector('.custom-tag');
  await select.updateComplete;

  select.getTag = (option, index) => {
    // Reuse the icon from the matching wa-option
    const name = option.querySelector('wa-icon[slot="start"]').name;

    // Return a string, a Lit Template, or an HTMLElement.
    // Include data-value so the tag can be removed properly.
    return `
      <wa-tag with-remove data-value="${option.value}">
        <wa-icon name="${name}"></wa-icon>
        ${option.label}
      </wa-tag>
    `;
  };
</script>

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

Link to This Section

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 a value starts 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.
Bar Baz Add "foo" option

Add "foo" option

Bar Baz Add "foo" option (selected)

Add "foo" option


Reset Show FormData


<form id="lazy-options-example">
  <div>
    <wa-select name="select-1" value="foo" label="Single select (with existing options)">
      <wa-option value="bar">Bar</wa-option>
      <wa-option value="baz">Baz</wa-option>
    </wa-select>

    <wa-divider></wa-divider>

    <wa-button appearance="filled" type="button">Add "foo" option</wa-button>
  </div>

  <br />

  <div>
    <wa-select name="select-2" value="foo" label="Single select (with no existing options)"> </wa-select>

    <wa-divider></wa-divider>

    <wa-button appearance="filled" type="button">Add "foo" option</wa-button>
  </div>

  <br />

  <div>
    <wa-select name="select-3" multiple label="Multiple select (with existing selected options)">
      <wa-option value="bar" selected>Bar</wa-option>
      <wa-option value="baz" selected>Baz</wa-option>
    </wa-select>

    <wa-divider></wa-divider>

    <wa-button appearance="filled" type="button">Add "foo" option (selected)</wa-button>
  </div>

  <br />

  <div>
    <wa-select name="select-4" value="foo" multiple label="Multiple select (with no existing options)"> </wa-select>

    <wa-divider></wa-divider>

    <wa-button appearance="filled" type="button">Add "foo" option</wa-button>
  </div>

  <br /><br />

  <div style="display: flex; gap: 16px;">
    <wa-button appearance="filled" type="reset">Reset</wa-button>
    <wa-button appearance="filled" type="submit" variant="neutral">Show FormData</wa-button>
  </div>

  <br />

  <pre hidden><code id="lazy-options-example-form-data"></code></pre>

  <br />
</form>

<script type="module">
  function addFooOption(e) {
    const addFooButton = e.target.closest("wa-button[type='button']");
    if (!addFooButton) {
      return;
    }
    const select = addFooButton.parentElement.querySelector('wa-select');

    if (select.querySelector("wa-option[value='foo']")) {
      // Foo already exists. no-op.
      return;
    }

    const option = document.createElement('wa-option');
    option.setAttribute('value', 'foo');
    option.selected = true;
    option.innerText = 'Foo';

    // For the multiple select with existing selected options, make the new option selected
    if (select.getAttribute('name') === 'select-3') {
      option.selected = true;
    }

    select.append(option);
  }

  function handleLazySubmit(event) {
    event.preventDefault();

    const formData = new FormData(event.target);
    const codeElement = document.querySelector('#lazy-options-example-form-data');

    const obj = {};
    for (const key of formData.keys()) {
      const val = formData.getAll(key).length > 1 ? formData.getAll(key) : formData.get(key);
      obj[key] = val;
    }

    codeElement.textContent = JSON.stringify(obj, null, 2);

    const preElement = codeElement.parentElement;
    preElement.removeAttribute('hidden');
  }

  const container = document.querySelector('#lazy-options-example');
  container.addEventListener('click', addFooOption);
  container.addEventListener('submit', handleLazySubmit);
</script>

Throughout, the select prioritizes user interactions and explicit selections over programmatic changes, keeping behavior predictable even with dynamically loaded content.

API

Link to This Section

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@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

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' | 'filled-outlined'
Default 'outlined'
disabled
disabled
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
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
multiple
multiple
Allows more than one option to be selected.
Type boolean
Default false
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 '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 []
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
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
withLabel
with-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

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

Link to This Section

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

Link to This Section

Learn more about custom states.

Name Description CSS selector
blank The select 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 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

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

  • <wa-button>
  • <wa-icon>
  • <wa-option>
  • <wa-popup>
  • <wa-spinner>
  • <wa-tag>
Need a hand? Report a bug Ask for help
Go Make Something Awesome
Version 3.10.0 © Fonticons, Inc.
  • Terms
  • Privacy
  • Refunds
  • Core License
  • Pro License

Quick Links

  • Components
  • CSS Utilities
  • Theming
  • Using with AI
  • Changelog
  • Help & Support

Recent Searches

    D'oh! No results for “”

    Suggest on GitHub Ask on Discord
    Navigate Select
    Close Esc