Skip to main content

Select

The qds-select element represents a control that provides a menu of options.

— Definition from the MDN web docs

Usage​

Use <qds-select> to create a customizable select menu with options and optgroups, supporting single or multiple selections, and various states like disabled or required. Nest <option> and <optgroup> elements within it to define the menu's options and categories.

Loading...
Live Editor
<qds-select>
  <option value="">Choose an option</option>
  <optgroup label="4-legged pets" disabled>
    <option value="dog">Dog</option>
    <option value="cat">Cat</option>
    <option value="hamster">Hamster</option>
  </optgroup>
  <optgroup label="Flying pets">
    <option value="parrot">Parrot</option>
    <option value="macaw" disabled>
      Macaw
    </option>
    <option value="albatross">Albatross</option>
  </optgroup>
</qds-select>

Size​

select follow the transversal control size principles. Use the standard size unless you're in one of the specific contexts described on that page.

Loading...
Live Editor
<div class="qds-controls qds-related">
  <div class="qds-controls qds-related flex flex-row">
    <qds-label inline text="Standard size:"></qds-label>
    <qds-select size="standard">
      <option value="">Choose an option</option>
    </qds-select>
  </div>
  <div class="qds-controls-large qds-related flex flex-row">
    <qds-label inline size="large" text="Large size:"></qds-label>
    <qds-select size="large">
      <option value="">Choose an option</option>
    </qds-select>
  </div>
  <div class="qds-controls-small qds-related flex flex-row">
    <qds-label inline size="small" text="Small size:"></qds-label>
    <qds-select size="small">
      <option value="">Choose an option</option>
    </qds-select>
  </div>
</div>

Multiple​

Indicates that multiple options can be selected in the list. If it is not specified, then only one option can be selected at a time. When multiple is specified, most browsers will show a scrolling list box instead of a single line dropdown.

Loading...
Live Editor
<qds-select multiple>
  <option value="">Choose an option</option>
  <optgroup label="4-legged pets" disabled>
    <option value="dog">Dog</option>
    <option value="cat">Cat</option>
    <option value="hamster">Hamster</option>
  </optgroup>
  <optgroup label="Flying pets">
    <option value="parrot">Parrot</option>
    <option value="macaw" disabled>
      Macaw
    </option>
    <option value="albatross">Albatross</option>
  </optgroup>
</qds-select>

Group​

When used in a group, use 16px horizontal spacing, the desktop.control.standard.gap.siblings.related token.

Loading...
Live Editor
<div class="qds-controls flex-row">
  <qds-select>
    <option value="">Choose an option</option>
  </qds-select>
  <qds-select>
    <option value="">Choose an option</option>
  </qds-select>
  <div class="qds-controls qds-related flex flex-row">
    <qds-select>
      <option value="">Choose an option</option>
    </qds-select>
    <qds-select>
      <option value="">Choose an option</option>
    </qds-select>
  </div>
</div>

In forms​

Follow the Forms design pattern guidelines to properly organize and space your form labels and controls.

Additional options​

Disabled​

Use the disabled attribute to disable the select. Clicks will be suppressed until the disabled state is removed.

Loading...
Live Editor
<qds-select disabled>
  <option>Choose an option</option>
</qds-select>

Required​

An <option> with a non-empty string value must be selected before this select can be submitted.

Loading...
Live Editor
<form class="qds-controls qds-related">
  <label class="qds-controls qds-related flex-row">
    <qds-label inline required text="Select option:"></qds-label>
    <qds-select required>
      <option value="">Choose an option</option>
      <optgroup label="4-legged pets" disabled>
        <option value="dog">Dog</option>
        <option value="cat">Cat</option>
        <option value="hamster">Hamster</option>
      </optgroup>
      <optgroup label="Flying pets">
        <option value="parrot">Parrot</option>
        <option value="macaw" disabled>
          Macaw
        </option>
        <option value="albatross">Albatross</option>
      </optgroup>
    </qds-select>
  </label>
  <qds-button text="Submit" />
</form>

Implementation tips​

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

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

import { defineCustomElementQdsSelect } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsSelect()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
autocomplete / autoComplete
AutoComplete | undefined

Provides a hint for a user agent's autocomplete feature. See the HTML autocomplete attribute for a complete list of values and details on how to use autoComplete.

undefined
autofocus / autoFocus
boolean | undefined

Specify whether the select should have focus when the page loads.

undefined
disabled
boolean | undefined

Prevents the select from being interacted with: it cannot be pressed or focused.

undefined
form
HTMLFormElement | null | string

The <form> element to associate the select with (its form owner).

The value of this attribute must be the id of a <form> in the same document. If this attribute is not set, the <qds-select> is associated with its ancestor <form> element, if any.

This attribute lets you associate <qds-select> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

null
length
number

Returns the number of elements in the <option>s collection.

0
multiple
boolean | undefined

Indicates that multiple options can be selected in the list. If it is not specified, then only one option can be selected at a time. When multiple is specified, most browsers will show a scrolling list box instead of a single line dropdown.

undefined
name
string | undefined

The name of the select, which is submitted with the form data.

undefined
HTMLOptionsCollection

An HTMLOptionsCollection of the <option> elements contained by the <qds-select> element.

EMPTY_OPTIONS_COLLECTION
required
boolean | undefined

An <option> with a non-empty string value must be selected before this select can be submitted.

See Client-side validation and the HTML attribute: required for more information.

undefined
selected-index / selectedIndex
number

The index of the first or last selected <option> element, depending on the value of multiple. The value -1 indicates that no element is selected.

-1
HTMLCollectionOf<HTMLOptionElement>

Collection of the <option> elements contained within the <qds-select> element that are currently selected.

EMPTY_OPTIONS_COLLECTION
size
"large" | "small" | "standard" | undefined

The select's size.

NOTE: The native size HTML attribute is not supported. CSS height should be used instead if this functionality is needed.

'standard'
type
"select-multiple" | "select-one"

Returns select-multiple if the multiple attribute is true; select-one otherwise.

'select-one'
validation-message / validationMessage
string

The error message that would be shown to the user if the <qds-select> was to be checked for validity.

''
ValidityState

The ValidityState object for this <qds-select>.

VALID_STATE
value
string | undefined

The value property of the first selected <option> element, or the empty string if no options are selected.

''
will-validate / willValidate
boolean

True if <qds-select> will be validated when the form is submitted; false otherwise.

false

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the select loses focus.

qdsChange
void

Emitted when an alteration to the select's value is committed by the user.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the select gains focus.

qdsInput
{ readonly data: string | null; readonly inputType: string; readonly isComposing: boolean; }

Emitted when the select's value changes.

Last updated on