Select

Select allows users to make a single selection or multiple selections from a list of options.

Code

Relies on the third-party librarySelect2for its features and functionality.View all resources

Stacked layout

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts.

Label (Required) Help or instructional text goes here

<div class="form-group form-group--stacked">
  <label for="selectField" class="form-label"> … </label>
  <span class="help-block">
    <span class="help-block__text"> … </span>
    <span class="help-block__link"> … </span>
    <!-- optional warning message -->
    <div class="text-warning d-flex align-items-center space-x space-x-3">
      <svg class="icon icon-16" aria-hidden="true">
        <use xlink:href="/assets/svg/solid.svg#bell-on"></use>
      </svg>
      …
    </div>
    <!-- /optional warning message -->
  </span>
  <!-- error handling -->
  <div class="form-error" role="alert">…</div>
  <!-- /error handling -->
  <select id="selectField" data-js="select2">
    <option selected>Selected value</option>
    <option>Option two</option>
    <option>Option three</option>
  </select>
</div>

Symbols prefixed by underscore ("_")

When referencing/naming Symbol with a form input, any argument/option/variable that are endemic to the input itself (i.e. "id", "placeholder", "required") are **not** preceded by an _underscore. In other cases, an _underscore precedes to denote it affects the output of a container/parent element, or a sibling.

@selectField(myForm(""),
  Symbol("_label") -> "",
  Symbol("id") -> "",
  Symbol("required") -> false,
  Symbol("_markRequired") -> false,
  Symbol("_markOptional") -> false,
  Symbol("autocomplete") -> false,
  Symbol("readOnly") -> false,
  Symbol("disabled") -> false,
  Symbol("_help") -> "",
  Symbol("_helpLink") -> <a href="#">Link</a>,
  Symbol("class") -> "",
  Symbol("_class") -> "",
)

NameTypeDescriptionDefault valueCopy

id
string (required)
adds an id to the input and a for attribute to the associated label label
blank
_label
string
Text that describes the control. Will be both visible and clickable.
blank
required
boolean
Require a valid input value from the user.
false
_markRequired
boolean
A visual “required” indicator
false
_markOptional
boolean
A visual “optional” indicator
false
readOnly
boolean
Disable editing of the input.
false
disabled
boolean
Sets the field as to appear disabled, users will not be able to interact with the text field.
false
class
string
adds class="" to the input
blank
_class
string
adds class="" to the container div (.form-check)
blank
_help
string
outputs additional help or instructional text
blank
_helpLink
html block (no quotes)
appends a link to help or instructional text
blank

This component leverages React Select, but with a subset of props. Ask a dev lead for more documentation on this component.

import {SelectControl} from 'react-p21';

<SelectControl>…</SelectControl>;

Horizontal layout

Side labels are most useful when vertical space is limited.

HTML
Twirl

<div class="form-group row">
  <div class="col-sm-3 col-md-2 d-md-flex text-md-right flex-column align-items-end">
    <label class="col-form-label" for="selectField">…</label>
    <span class="help-inline">(Required)</span>
  </div>
  <div class="col-sm-9 col-md-10 input-width--md">
    <input class="form-control" id="selectField" required="true" type="text" placeholder="Placeholder" />
    <!-- error handling -->
    <div class="form-error" role="alert">…</div>
    <!-- /error handling -->
    <span class="help-block">
      <span class="help-block__text"> … </span>
      <!-- optional warning message -->
      <div class="text-warning d-flex align-items-center space-x space-x-3">
        <svg class="icon icon-16" aria-hidden="true">
          <use xlink:href="/assets/svg/solid.svg#bell-on"></use>
        </svg>
        …
      </div>
      <!-- /optional warning message -->
    </span>
  </div>
</div>

@standardSelect(myForm(""),
  …
)

(See Twirl for stacked layouts)

Appearance

<div class="custom-select--link">…</div>

<div class="custom-select--link">
  <label class="custom-select__label" for="selectInput">…</label>
  <select multiple id="selectInput" data-js="select2">
    …
  </select>
</div>