• Light
  • Dark
  • Auto
  • Default
  • Indigo
  • Blue
  • Green
  • Red
  • Gray

Select

An HTML element, typically used in a form.

Examples

Select
Loading live example...

View in Pajamas UI Kit →

Structure

TODO:
Add structure image. Create an issue

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

TODO:
Add appearance. Create an issue

Behavior

TODO:
Add behavior. Create an issue

Accessibility

  • When using GlFormGroup, the label prop alone does not give the input an accessible name.
  • The label-for prop must also be provided to give the input an accessible name.

Select with label

With visible label
Loading live example...

Select with hidden label

With hidden label
Loading live example...

Code reference

GlFormSelect is typically wrapped in a GlFormGroup, which supplies the label and layout.

In a form group
Loading live example...

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 on v-model when the option is selected. Can be a string, number, or simple object. Avoid complex types.
  • text: The display text. If value is missing, text is used as the value.
  • disabled: When true, 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.

With options prop
Loading live example...

Option groups

To group options, add an object with a label for the group's name and an options array.

With option groups
Loading live example...

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.

With option elements
Loading live example...

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.

Combining options prop and option elements
Loading live example...

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.

With placeholder option
Loading live example...

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).

With custom field names
Loading live example...

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:

  • xs
  • sm
  • md
  • lg
  • xl
  • 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.
  • null Displays 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

value

undefined Current value of the select. Should be set to an array when the 'multiple' prop is set

undefined

options

array|object Array of items to render in the component

undefined

selectSize

number When set to a number larger than 0, will set the number of display option rows. Note not all browser will respect this setting

0

id

string Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed

undefined

plain

boolean Render the form control in plain mode, rather than custom styled mode

false

size

string Set the size of the component's appearance. 'sm', 'md' (default), or 'lg'

undefined

ariaInvalid

boolean|string Optional value to set for the 'aria-invalid' attribute. Supported values are 'true' and 'false'. If not set, the 'state' prop will dictate the value

false

state

boolean Controls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state

null

valueField

string Field name in the `options` array that should be used for the value

'value'

labelField

string The key to use from the option object to get the label

'label'

optionsField

string The key to use from the option object to get the options

'options'

textField

string Field name in the `options` array that should be used for the text label

'text'

disabledField

string Field name in the `options` array that should be used for the disabled state

'disabled'

htmlField

string Field name in the `options` array that should be used for the html label instead of text field

'html'

multiple

boolean When set, allows multiple options to be selected (multi-select)

false

autofocus

boolean When set to `true`, attempts to auto-focus the control when it is mounted, or re-activated when in a keep-alive. Does not set the `autofocus` attribute on the control

false

disabled

boolean When set to `true`, disables the component's functionality and places it in a disabled state

false

form

string ID of the form that the form control belongs to. Sets the `form` attribute on the control

undefined

name

string Sets the value of the `name` attribute on the form control

undefined

required

boolean Adds the `required` attribute to the form control

false

width

string|object Maximum width of the Select

null

selectClass

string|object|array Additional CSS class(es) to apply to the select element.

''

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

any Emitted when the select value changes

change

any Emitted when the select value changes via user interaction

Last updated at: