Select A list of mutually exclusive options in a dropdown.

Table of contents


Usage guidelines

When to use
  • Use a select when one option can be selected out of at least five.
  • When one option can be selected out of fewer than five, use radio buttons, space permitting.
  • When there are two options, and they are about turning something on or off, or enabling / disabling the same thing, use a switch.
How to use
  • Selects should always include a label.
  • Selects may optionally include placeholder text, but this does not replace the label.
  • Add placeholder text by including an option that has a placeholder attribute.
  • A placeholder option is useful for when you want the selection of any option to be opt-in. Without a placeholder option, the first option in the list will be selected by default.
  • Use sentence case for both the label and the placeholder text.
Accessibility
  • Placeholder text isn’t always visible and may be inaccessible on screenreaders. It should contain only additional, optional information that reinforces the label rather than replaces it.
  • Native select element keyboard support is carried over to Resonance selects.
Content guidelines
  • When including placeholder text, follow the pattern of the label and include an article (e.g., a, an). Don’t use Select one as a catchall.
    • Example for category:
      • Select label: Category
      • Placeholder text: Select a category


Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
sizestringSet select box size
  • small
disabledbooleanSet initial state to disabled
requiredbooleanSet required state
errorstringSet error state along with message
infostringSet info state along with message

API

NameTypeDataDescription
disabledpropertybooleanGet/set disabled state
errorpropertystringGet/set error state (pass string to set message)
infopropertystringGet/set info state (pass string to set message)

Notes

Depends on:
Required DOM

Without these, the component will throw an error on render.

  • <option> - Select options
Supported optional DOM

If added as children, these elements will receive specific styles and/or functionality.

  • <label> - Select label

History

VersionNote
0.21.4Adds variable fallbacks that satisfy updated linting rules, package upgrades cause CSS build to remove -moz-appearance property
0.20.1Adds color styles for disabled options for Firefox
0.19.0Changes 'error' attribute type to string; adds 'info' attribute, which renders information below the select.
0.16.0Remove 1px-from-top position adjustment for the actual selects relative to the res-select container.
0.15.9Increase default-sized select height (39px -> 48px) and font size (13px -> 15px). Prevent clipping of descenders. Remove box-shadow.
0.15.0Tweak line height in label
0.14.0Add required and error attributes.
0.12.0Apply new spacing scale.
0.11.0Tweaks to accommodate new icon set.
0.10.0Color update
0.7.0Web component refactor. Removed value api method
0.5.0Full refactor. Removed the split design completely.
0.2.0Initial build to spec.