Select - Elements ​
A select is a form input component that lets users choose one option from a predefined list.
Accessibility ​
If a visible label isn't specified, an aria-label must be provided to the text field for accessibility. If the field is labeled by a separate element, an aria-labelledby property must be provided using the id of the labeling element instead.
Usage ​
<w-select label="Berries">
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Validation ​
Set the invalid attribute to display a textfield as invalid.
invalid should be paired with help-text to provide feedback to the user about how to correct the error.
<w-select label="Berries" invalid help-text="Select a red berry">
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries" selected>Cloudberries</option>
</w-select>Examples ​
<w-select label="Berries">
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Placeholder ​
A select doesn't have a placeholder as such, but an <option> with an empty value gives a similar result.
<w-select label="Berries">
<option value="">Select an option</option>
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Optional ​
Add the optional prop to indicate that the select is not required. To make the select optional you must add an <option> with an empty value.
<w-select label="Berries" optional>
<option value="">Select an option</option>
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Help text ​
Use help-text to give additional context when the label and options are not enough.
<w-select label="Berries" help-text="We assume this is your jam">
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>No visual label ​
You must set either an aria-label or an aria-labelledby.
<w-select aria-label="Berries">
<option value="raspberries">Raspberries</option>
<option value="strawberries" selected>Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Disabled ​
Keep in mind that using disabled is an anti-pattern.
There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.
Please consider more informative alternatives before choosing to use disabled on an element.
<w-select label="Berries" disabled>
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Read only ​
The readonly boolean attribute makes the selection immutable. Unlike disabled the select remains focusable. See MDN docs for more information.
<w-select label="Berries" readonly>
<option value="raspberries">Raspberries</option>
<option value="strawberries">Strawberries</option>
<option value="cloudberries">Cloudberries</option>
</w-select>Styling API ​
<w-select> API ​
Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
Properties ​
| Name | Type | Default | Summary |
|---|---|---|---|
| always | boolean | false | Whether to always show a hint. Deprecated: Use help-text instead and only set it if you want to display the help text. |
| auto-focus | boolean | false | Whether the element should receive focus on render. Deprecated: Use the native autofocus attribute instead. |
| autofocus | boolean | false | Whether the element should receive focus on render |
| disabled | boolean | false | Renders the field in a disabled state. |
| help-text | string | - | The content displayed as the help text. |
| hint | string | - | The content displayed as the help text. Deprecated: Use help-text instead. |
| invalid | boolean | false | Renders the field in an invalid state. |
| label | string | - | The content to display as the label. |
| name | string | - | The name of the select when submitting the form. |
| optional | boolean | false | Whether to show the optional indicator after the label. |
| read-only | boolean | false | Renders the field in a readonly state. Deprecated: Use the native readonly attribute instead. |
| readonly | boolean | false | Renders the field in a readonly state. |
| value | string | - | Lets you set the current value. |
Property Details ​
always ​
Deprecated: Use help-text instead and only set it if you want to display the help text.
Whether to always show a hint.
- Type:
boolean - Default:
false
auto-focus ​
Deprecated: Use the native autofocus attribute instead.
Whether the element should receive focus on render.
- Type:
boolean - Default:
false
autofocus ​
Whether the element should receive focus on render
- Type:
boolean - Default:
false
disabled ​
Renders the field in a disabled state.
- Type:
boolean - Default:
false
help-text ​
The content displayed as the help text.
Paired with invalid to show the text as a validation error.
- Type:
string - Default:
-
hint ​
Deprecated: Use help-text instead.
The content displayed as the help text.
- Type:
string - Default:
-
invalid ​
Renders the field in an invalid state.
Paired with help-text to provide feedback about the error.
- Type:
boolean - Default:
false
label ​
The content to display as the label.
- Type:
string - Default:
-
name ​
The name of the select when submitting the form.
- Type:
string - Default:
-
optional ​
Whether to show the optional indicator after the label.
- Type:
boolean - Default:
false
read-only ​
Deprecated: Use the native readonly attribute instead.
Renders the field in a readonly state.
- Type:
boolean - Default:
false
readonly ​
Renders the field in a readonly state.
- Type:
boolean - Default:
false
value ​
Lets you set the current value.
- Type:
string - Default:
-
Events ​
change ​
- Type:
CustomEvent
Questions? ​
Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system