Select
An HTML element, typically used in a form.
Examples
Structure
Guidelines
When to use
- To indicate a selection of a single item from a list of options.
- To present sort options when the sort order button isn't required (see the sorting component for a comparison).
When not to use
- If there are five or less options to select from or the user needs to easily see all of options, then consider using radio buttons instead.
- If more than one option can be selected, consider using checkboxes instead.
- If the option is a binary decision that takes immediate effect, consider using a toggle instead.
- If selecting from a list of options outside of a form or for more complex interactions, then a combobox is preferred.
Appearance
Behavior
Accessibility
- When using
GlFormGroup, thelabelprop alone does not give the input an accessible name. - The
label-forprop must also be provided to give the input an accessible name.
Select with label
Select with hidden label
Code reference
GlFormSelect is typically wrapped in a GlFormGroup, which supplies the label and layout.
Options
Supply options with the options prop, as <option> and <optgroup> children in the default slot, or both.
Options prop
Each entry in options can be a string or an object with these fields:
value: The value set onv-modelwhen the option is selected. Can be a string, number, or simple object. Avoid complex types.text: The display text. Ifvalueis missing,textis used as the value.disabled: Whentrue, the option can't be selected.
A string entry is used as both the value and the text. Strings and objects can be mixed in the same array.
Option groups
To group options, add an object with a label for the group's name and an options array.
Option elements
Options can also be supplied as <option> and <optgroup> children. This is useful when each option needs its own markup, or when the list is rendered with v-for.
Combining the options prop and option elements
Option elements in the default slot appear after the options from the options prop. To place them before, use the first slot.
Placeholder option
If the initial v-model value doesn't match any option, the select renders with nothing selected. On iOS, the user then can't select the first option, because no change event fires. Provide a disabled first option with an empty value instead.
Custom field names
To read option fields from other property names, set value-field, text-field, disabled-field, label-field (group name), or options-field (group options).
Multiple select support (deprecated)
NOTE: Use
<gl-collapsible-listbox>instead for selecting multiple values.
Sizing
Set the maximum width of <gl-form-select> with the width prop, as with <gl-form-input>. The available sizes are:
xssmmdlgxl- unset or
null
By default <gl-form-select> will occupy the full width of the container that
it appears in.
Autofocus
When the autofocus prop is set on <gl-form-select>, the select will be auto-focused when it is
inserted (i.e. mounted) into the document or re-activated when inside a Vue <keep-alive>
component. Note that this prop does not set the autofocus attribute on the select, nor can it
tell when the select becomes visible.
Contextual states
<gl-form-select> includes validation styles for valid and invalid states.
Generally speaking, you'll want to use a particular state for specific types of feedback:
false(denotes invalid state) is great for when there's a blocking or required field. A user must fill in this field properly to submit the form.true(denotes valid state) is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fields.nullDisplays no validation state (neither valid nor invalid)
To apply one of the contextual states on <gl-form-select>, set the state prop to false
(for invalid), true (for valid), or null (no validation state).
Conveying contextual validation state to assistive technologies and colorblind users
Using these contextual states to denote the state of a form control only provides a visual, color-based indication, which will not be conveyed to users of assistive technologies - such as screen readers - or to colorblind users.
Ensure that an alternative indication of state is also provided. For instance, you could include a
hint about state in the form control's <label> text itself, or by providing an additional help
text block (via <gl-form-group>). Specifically for assistive technologies,
invalid selects get an aria-invalid="true" attribute (see below).
ARIA aria-invalid attribute
When state is false, <gl-form-select> sets aria-invalid="true" on the select automatically.
Setting the aria-invalid prop as well isn't necessary.
To mark the select as invalid for assistive technologies without applying the visual invalid state,
set the aria-invalid prop to true and leave state unset.
GlFormSelect
import { GlFormSelect } from '@gitlab/ui';Props
Name | Description | Default |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Slots
Name | Description |
|---|---|
first | Slot to place options or option groups above options provided via the 'options' prop |
default | Content to place in the form select after 'options' prop options |
Events
Name | Description |
|---|---|
input |
|
change |
|
Last updated at: