Components

Checkboxes

Let users select one or more options by using the checkboxes component.

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

Which types of waste do you transport?

Select all that apply.

Value of v-model: []

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

const wasteTypes = ref([])
</script>

<template>
  <gv-checkboxes
    v-model="wasteTypes"
    :legend-is-page-heading="true"
    legend-class="govuk-fieldset__legend--l"
  >
    <template #legend>Which types of waste do you transport?</template>
    <template #hint>Select all that apply.</template>
    <gv-checkbox label="Waste from animal carcasses" value="animal"/>
    <gv-checkbox label="Waste from mines or quarries" value="mines"/>
    <gv-checkbox label="Farm or agricultural waste" value="farm"/>
  </gv-checkboxes>
  
  <gv-inset-text aria-live="polite">
    Value of v-model: {{wasteTypes}} 
  </gv-inset-text>
</template>

Using v-model with checkboxes

The checkboxes component supports the same v-model binding behaviour as <input type="checkbox">.

You can bind individual checkboxes to separate refs, or the whole checkbox group to an array—or both.

If the checkbox group is bound to an array, you must provide a value for each checkbox. The array will contain the values of every checked box.

If an individual checkbox is bound to a ref, by default the ref will be set to true if the box is checked and false if it's not. You can override this with the true-value and false-value props. true-value and false-value won't work if the individual checkbox is bound to a ref and the checkbox group is bound to an array.

Which countries have you visited?

Select all that apply.

Value of v-model: []
Has visited England: false

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

const countries = ref([])
const englandVisited = ref(false)
</script>

<template>
  <gv-checkboxes
    v-model="countries"
    :legend-is-page-heading="true"
    legend-class="govuk-fieldset__legend--l"
  >
    <template #legend>Which countries have you visited?</template>
    <template #hint>Select all that apply.</template>
    <gv-checkbox value="england" v-model="englandVisited">England</gv-checkbox>
    <gv-checkbox value="scotland">Scotland</gv-checkbox>
    <gv-checkbox value="wales">Wales</gv-checkbox>
    <gv-checkbox value="northernireland">Northern Ireland</gv-checkbox>
  </gv-checkboxes>
  
  <gv-inset-text aria-live="polite">
    Value of v-model: {{countries}}<br/>
    Has visited England: {{englandVisited}}
  </gv-inset-text>
</template>

Standalone checkboxes

If you have a single, standalone checkbox which doesn't need a fieldset legend, you can use gv-checkbox on its own without a gv-checkboxes wrapper.

Value of v-model: No

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

const termsAccepted = ref('No')
</script>

<template>
  <gv-checkbox v-model="termsAccepted" true-value="Yes" false-value="No">I accept the terms and conditions</gv-checkbox>
  
  <gv-inset-text aria-live="polite">
    Value of v-model: {{termsAccepted}}
  </gv-inset-text>
</template>

Showing hints

You can add hints to both the checkbox group and individual checkboxes using the hint prop or slot.

What is your nationality?

If you have dual nationality, select all options that are relevant to you.

including English, Scottish, Welsh and Northern Irish

<gv-checkboxes
  :legend-is-page-heading="true"
  legend-class="govuk-fieldset__legend--l"
>
  <template #legend>What is your nationality?</template>
  <template #hint>
    If you have dual nationality, select all options that are relevant to you.
  </template>
  <gv-checkbox value="british" hint="including English, Scottish, Welsh and Northern Irish">British</gv-checkbox>
  <gv-checkbox value="irish">Irish</gv-checkbox>
  <gv-checkbox value="other">Citizen of another country</gv-checkbox>
</gv-checkboxes>

Adding an option for 'none'

If you need to give the user a 'none of the above' option, set the exclusive prop to true on the last checkbox in the group. You should also set divider (usually to 'or') to set the text show above this option.

If the user checks an exclusive checkbox, any other checkboxes will be unchecked. If the user then checks another box, the exclusive checkbox will be unchecked.

Will you be travelling to any of these countries?

Select all that apply.

or

Value of v-model: []

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

const countries = ref([])
</script>

<template>
  <gv-checkboxes
    v-model="countries"
    :legend-is-page-heading="true"
    legend-class="govuk-fieldset__legend--l"
  >
    <template #legend>Will you be travelling to any of these countries?</template>
    <template #hint>Select all that apply.</template>
    <gv-checkbox value="france">France</gv-checkbox>
    <gv-checkbox value="portugal">Portugal</gv-checkbox>
    <gv-checkbox value="spain">Spain</gv-checkbox>
    <gv-checkbox value="none" :exclusive="true" divider="or">
      No, I will not be travelling to any of these countries
    </gv-checkbox>
  </gv-checkboxes>
  
  <gv-inset-text aria-live="polite">
    Value of v-model: {{countries}}
  </gv-inset-text>
</template>

Conditionally revealing a related question

You can show conditional content that's only shown when a checkbox is checked using the conditional slot.

How would you like to be contacted?

Select all options that are relevant to you.

<gv-checkboxes
  :legend-is-page-heading="true"
  legend-class="govuk-fieldset__legend--l"
>
  <template #legend>
    How would you like to be contacted?
  </template>
  <template #hint>
    Select all options that are relevant to you.
  </template>
  <gv-checkbox value="email"> 
    Email
    <template #conditional>
      <gv-input label="Email address" class="govuk-!-width-one-half" type="email" :spellcheck="false" autocomplete="email"/>
    </template>
  </gv-checkbox>
  <gv-checkbox value="phone">
    Phone
    <template #conditional>
      <gv-input label="Phone number" class="govuk-!-width-one-half" type="tel" autocomplete="tel"/>
    </template>
  </gv-checkbox>
  <gv-checkbox value="text">
    Text message
    <template #conditional>
      <gv-input label="Mobile phone number" class="govuk-!-width-one-half" type="tel" autocomplete="tel"/>
    </template>
  </gv-checkbox>
</gv-checkboxes>

Smaller checkboxes

Set the size prop to small to use smaller checkboxes.

Organisation

<gv-checkboxes
  :legend-is-page-heading="true"
  legend-class="govuk-fieldset__legend--m"
  legend="Organisation"
  size="small"
>
  <gv-checkbox>HM Revenue and Customs (HMRC)</gv-checkbox>
  <gv-checkbox>Employment Tribunal</gv-checkbox>
  <gv-checkbox>Ministry of Defence</gv-checkbox>
  <gv-checkbox>Department for Transport</gv-checkbox>
</gv-checkboxes>

Error messages

Set the error-message prop to display an error.

What is your nationality?

If you have dual nationality, select all options that are relevant to you.

Select if you are British, Irish or a citizen of a different country

including English, Scottish, Welsh and Northern Irish

<gv-checkboxes
  :legend-is-page-heading="true"
  legend-class="govuk-fieldset__legend--l"
  error-message="Select if you are British, Irish or a citizen of a different country"
>
  <template #legend>What is your nationality?</template>
  <template #hint>
    If you have dual nationality, select all options that are relevant to you.
  </template>
  <gv-checkbox value="british" hint="including English, Scottish, Welsh and Northern Irish">British</gv-checkbox>
  <gv-checkbox value="irish">Irish</gv-checkbox>
  <gv-checkbox value="other">Citizen of another country</gv-checkbox>
</gv-checkboxes>

GvCheckboxes

Props

Name	Type	Description
modelValue	array	The array of selected checkbox values. In most cases you should use v-model instead of setting this prop directly.
name	string	The value of the name attribute to apply to all checkboxes in this group. If you don't provide a name, one will be generated automatically.
size	string	The size of the checkboxes in this group. Allowed values: normal, small. Defaults to 'normal'.
fieldsetDescribedBy	string	One or more element IDs to add to the aria-describedby attribute, used to provide additional descriptive information for screenreader users.
fieldsetClass	string|array|object	Classes to add to the fieldset container. You can bind a string, an array or an object, as with normal Vue class bindings.
fieldsetRole	string	Optional ARIA role attribute to add to the fieldset container.
legend	string	Text to use within the legend. If content is provided in the legend slot, this prop will be ignored.
legendClass	string|array|object	Classes to add to the legend. You can bind a string, an array or an object, as with normal Vue class bindings.
legendIsPageHeading	boolean	Whether the legend also acts as the heading for the page.
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.

Slots

Name	Description
legend	The content of the legend. If content is provided in this slot, the legend 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.
default	A list of gv-checkboxes

GvCheckbox

Props

Name	Type	Description
modelValue	null	True if the checkbox is checked, false otherwise (or the value of the trueValue or falseValue props if they have been set). In most cases you should use v-model instead of setting this prop directly.
trueValue	boolean	The value to set the v-model to if the checkbox is checked. Defaults to true.
falseValue	boolean	The value to set the v-model to if the checkbox is not checked. Defaults to false.
id	string	The ID for this checkbox. If you don't provide an ID, one will be generated automatically.
name	string	The value of the name attribute for this checkbox. If you don't provide a name, one will be generated automatically.
value	null	If the parent checkbox group has a v-model array, this value will be added to the array if the checkbox is checked.
divider	string	The divider text to show above the checkbox if this checkbox is exclusive. This should usually be 'or'.
exclusive	boolean	Whether checking this checkbox should deselect all other checkboxes in this group.
disabled	boolean	If true, checkbox will be disabled.
label	string	Text to use within the label. If content is provided in the default slot, this prop will be ignored.
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.

Slots

Name	Description
default	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.
conditional	Content to show if the checkbox is checked.