Checkboxes

When to use this component

Use the checkboxes component to assist users in selecting multiple options from a list or toggling a single option on or off. When submitting data to CRM, this component is suitable for boolean, select or text type target fields.

If required, you can use custom script to associate records where each checkbox selection refers to a parent-child or many-to-many relationship record.

When to not use this component

Avoid using the checkboxes component if users can only choose one option from a selection. Instead, opt for the radios component.

How it works

Checkboxes are positioned to the left of their labels for enhanced visibility, particularly for users utilising screen magnifiers.

Unlike radios, users can select multiple options from a list of checkboxes. Do not assume users will understand the number of selectable options based solely on the visual distinction between radios and checkboxes.

If necessary, provide hint text such as 'Select all that apply' to clarify the selection process.

Avoid pre-selecting checkbox options as it may lead to users overlooking questions or providing incorrect answers.

Order checkbox options alphabetically by default.

HTML examples

Select the appropriate example from this page and directly integrate the HTML into your web template. You can customise these examples to align with your specific requirements, as indicated below. Refer to the layouts section for further guidance on structuring your web template.

If the component requires submission to a CRM field, ensure to replace the placeholder schema-name text in the HTML example with the actual target field schema name. Retain any prefixed or suffixed text related to the schema name. For instance, if the id attribute reads schema-name-hint in the example, ensure the replacement maintains the -hint suffix (e.g. dfe_field-hint).

This step is crucial for allowing the CRM helper framework to validate and submit data to CRM.

For single question pages

If presenting only one question on the page, designate the contents of the legend as the page heading. This practice ensures users of screen readers hear the contents only once.

You will need to include an empty {% title %} block in your web template to remove the default page header and avoid duplication.

Radio component

Which types of waste do you transport?

Replace 'schema-name' in the example by entering the schema name of your target CRM field.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Which types of waste do you transport?
      </h1>
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-1" name="schema-name" type="checkbox" value="carcasses">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name">
          Waste from animal carcasses
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-2" name="schema-name" type="checkbox" value="mines">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-2">
          Waste from mines or quarries
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-3" name="schema-name" type="checkbox" value="farm">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-3">
          Farm or agricultural waste
        </label>
      </div>
    </div>
  </fieldset>
</div>

Warning This is a basic web template page layout with a logged in user check and does not include additional liquid items which are common place on a CRM Portal, for example, web role, URL parameter or record checks.

{% extends 'DfE/Layouts/2ColumnWideLeft' %}

{% block title %}{% endblock %}   

{% block main %}
  {% unless user %}
    <script>
      window.location.href="{{ sitemarkers['DfE/Error/AccessDenied'].url }}"
    </script>
  {% endunless %}

  ## HTML content goes here ##

{% endblock %}

For multiple question pages

If presenting more than one question on the page, do not set the contents of the legend as the page heading.

Radio component

Which types of waste do you transport?

Replace 'schema-name' in the example by entering the schema name of your target CRM field.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend">
      Which types of waste do you transport?
    </legend>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-1" name="schema-name" type="checkbox" value="carcasses">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name">
          Waste from animal carcasses
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-2" name="schema-name" type="checkbox" value="mines">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-2">
          Waste from mines or quarries
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-3" name="schema-name" type="checkbox" value="farm">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-3">
          Farm or agricultural waste
        </label>
      </div>
    </div>
  </fieldset>
</div>

Warning This is a basic web template page layout with a logged in user check and does not include additional liquid items which are common place on a CRM Portal, for example, web role, URL parameter or record checks.

{% extends 'DfE/Layouts/2ColumnWideLeft' %} 

{% block main %}
  {% unless user %}
    <script>
      window.location.href="{{ sitemarkers['DfE/Error/AccessDenied'].url }}"
    </script>
  {% endunless %}

  ## HTML content goes here ##

{% endblock %}

Using hint text

Use hint text to provide relevant assistance to the majority of users, such as clarifying how their information will be used or where to locate it. The hint text block is demonstrated in the example below.

Please ensure the following:

• Use the hint text block appropriately
• Place the hint block correctly within your HTML component
• Add the aria-describedby attribute where necessary, for accessiblity. For checkboxes this is against the fieldset.

Avoid lengthy paragraphs and lists in hint text, as screen readers will read out the entire content, potentially frustrating users. Additionally, refrain from including links within hint text, as screen readers do not indicate that the text is a clickable link.

Radio component

Which types of waste do you transport?

Select all that apply.

Replace 'schema-name' in the example by entering the schema name of your target CRM field.

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset" aria-describedby="schema-name-hint">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h1 class="govuk-fieldset__heading">
        Which types of waste do you transport?
      </h1>
    </legend>
    <div id="schema-name-hint" class="govuk-hint">
      Select all that apply.
    </div>
    <div class="govuk-checkboxes" data-module="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-1" name="schema-name" type="checkbox" value="carcasses">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name">
          Waste from animal carcasses
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-2" name="schema-name" type="checkbox" value="mines">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-2">
          Waste from mines or quarries
        </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="schema-name-3" name="schema-name" type="checkbox" value="farm">
        <label class="govuk-label govuk-checkboxes__label" for="schema-name-3">
          Farm or agricultural waste
        </label>
      </div>
    </div>
  </fieldset>
</div>

Warning This is a basic web template page layout with a logged in user check and does not include additional liquid items which are common place on a CRM Portal, for example, web role, URL parameter or record checks.

{% extends 'DfE/Layouts/2ColumnWideLeft' %}

{% block title %}{% endblock %}   

{% block main %}
  {% unless user %}
    <script>
      window.location.href="{{ sitemarkers['DfE/Error/AccessDenied'].url }}"
    </script>
  {% endunless %}

  ## HTML content goes here ##

{% endblock %}

Additional examples

Additional examples can be found on the GOV.UK Design System:

• Add an option for 'none'
• Conditionally revealing a related question
• Smaller checkboxes

These examples will eventually be incorporated into this guidance, demonstrating how to use each of these additional examples with Power Pages. If you require assistance in the interim to adapt these additional examples for use with Power Pages and the CRM helper framework, please contact the Solutions Delivery Team.

Error messages

An error message is displayed next to the field and in the error summary when a validation error occurs. The CRM helper framework automatically handles error messages for specific error states, therefore you do not need to add any additional error containers to your HTML. Refer to the CRM helper framework guide to understand how to validate your front-end data.

Ensure that your component HTML and your inputs validation JavaScript object are structured correctly for your component type.

If nothing is selected and the question is required

Occasionally you may wish to employ error messages outside of the validation process. You can read about the functions available within the CRM helper framework to assist you with this.

Known issues

The CRM helper framework does not currently support submitting to multi-choice select fields in Dynamics 365. This issue has been added to the issues backlog in GitHub (opens in a new tab).

If you would like any additional advice or guidance with using these examples on Power Pages, please contact the Solutions Delivery Team.