Components

Select

The select component allows users to choose an option from a list.

See the GOV.UK Design System documentation on selects for more information on when to use this component.

<gv-select label="Sort by">
  <gv-select-option value="published">
    Recently published
  </gv-select-option>
  <gv-select-option value="updated">
    Recently updated
  </gv-select-option>
  <gv-select-option value="views">
    Most views
  </gv-select-option>
  <gv-select-option value="comments">
    Most comments
  </gv-select-option>  
</gv-select>

Binding with v-model and using events

The select component supports the same v-model binding behaviour as <select>.

Each option needs a value. The value of v-model will be set to the value of the selected option.

values can be simple types, like strings or numbers, or more complex objects.

You can also attach event listeners and they'll be bound to the underlying <select>.

<script setup lang="ts">
import { ref } from 'vue'

const sortOptions = [
  { label: 'Price, high to low', property: 'price', direction: 'descending' },
  { label: 'Price, low to high', property: 'price', direction: 'ascending' },
]

const selectedSort = ref(null)

function handleChange() {
  alert('You changed the sort value')
}
</script>

<template>
  <gv-select 
    v-model="selectedSort"
    label="Sort by"
    @change="handleChange"
  >
    <gv-select-option 
      v-for="sortOption in sortOptions" 
      :key="sortOptions.label" 
      :value="sortOption"
    >
      {{ sortOption.label }}
    </gv-select-option>
  </gv-select>
  
  <gv-inset-text v-if="selectedSort" aria-live="polite">
    Sorting by {{ selectedSort.label.toLowerCase() }}
  </gv-inset-text>
</template>

Select with hint

You can add a hint using the hint prop or slot.

This can be different to where you went before

<gv-select
  label="Choose location"
  hint="This can be different to where you went before"
 >
  <gv-select-option value="eastmidlands">East Midlands</gv-select-option>
  <gv-select-option value="eastofengland">East of England</gv-select-option>
  <gv-select-option value="london">London</gv-select-option>
  <gv-select-option value="northeast">North East</gv-select-option>
  <gv-select-option value="northwest">North West</gv-select-option>
  <gv-select-option value="southeast">South East</gv-select-option>
  <gv-select-option value="southwest">South West</gv-select-option>
  <gv-select-option value="westmidlands">West Midlands</gv-select-option>
  <gv-select-option value="yorkshire">Yorkshire and the Humber</gv-select-option>
</gv-select>

Error messages

Use the error-message prop or slot to show an error message if the user has not selected an option for a mandatory select.

This can be different to where you went before

Select a location

<gv-select
  label="Choose location"
  hint="This can be different to where you went before"
  error-message="Select a location"
 >
  <gv-select-option value="eastmidlands">East Midlands</gv-select-option>
  <gv-select-option value="eastofengland">East of England</gv-select-option>
  <gv-select-option value="london">London</gv-select-option>
  <gv-select-option value="northeast">North East</gv-select-option>
  <gv-select-option value="northwest">North West</gv-select-option>
  <gv-select-option value="southeast">South East</gv-select-option>
  <gv-select-option value="southwest">South West</gv-select-option>
  <gv-select-option value="westmidlands">West Midlands</gv-select-option>
  <gv-select-option value="yorkshire">Yorkshire and the Humber</gv-select-option>
</gv-select>

GvSelect

Props

Name	Type	Description
modelValue	string|number|boolean|object	The selected option's value. In most cases you should use v-model instead of setting this prop directly.
id	string	The ID for the select element. If you don't provide an ID, one will be generated automatically.
name	string	The value of the name attribute for the select element.
describedBy	string	One or more element IDs to add to the aria-describedby attribute, used to provide additional descriptive information for screenreader users.
disabled	boolean	If true, select box will be disabled. Use the disabled prop on each individual item to only disable certain options.
label	string	Text to use within the label. If content is provided in the default slot, this prop will be ignored.
labelIsPageHeading	boolean	Whether the label also acts as the heading for the page. Defaults to false.
labelClass	string|array|object	Classes to add to the label tag. You can bind a string, an array or an object, as with normal Vue class bindings.
hint	string	Text to use within the hint. If content is provided in the hint slot, this prop will be ignored.
hintClass	string|array|object	Classes to add to the hint span tag. You can bind a string, an array or an object, as with normal Vue class bindings.
errorMessage	string	Text to use within the error message. If content is provided in the error-message slot, this prop will be ignored.
errorMessageClass	string|array|object	Classes to add to the error message <p> tag. You can bind a string, an array or an object, as with normal Vue class bindings.
errorMessageVisuallyHiddenText	string	A visually hidden prefix used before the error message. Defaults to 'Error'.
formGroupClass	string|array|object	Classes to add to the form group. You can bind a string, an array or an object, as with normal Vue class bindings.
beforeInput	string	Text to add before the select. If content is provided in the before-input slot, this prop will be ignored.
afterInput	string	Text to add after the select. If content is provided in the after-input slot, this prop will be ignored.

Slots

Name	Description
label	The content of the label. If content is provided in this slot, the label prop will be ignored.
hint	The content of the hint. If content is provided in this slot, the hint prop will be ignored.
error-message	The content of the error message. If content is provided in this slot, the errorMessage prop will be ignored.
before-input	Content to add before the select. If content is provided in this slot, the beforeInput prop will be ignored.
default	A list of GvSelectOptions
after-input	Content to add after the select. If content is provided in this slot, the afterInput prop will be ignored.

GvSelectOption

Props

Name	Type	Description
text	string	Text for the option item. If content is provided in the default slot, this prop will be ignored.
value required	string|number|boolean|object	The value of this option. The parent GvSelect's v-model will be set to this value if the option is selected.
disabled	boolean	If true, option will be disabled.

Slots

Name	Description
default	The content of the option. If content is provided in this slot, the text prop will be ignored.