# Checkboxes ## Introduction Let users select one or more options. ## Guidance Find out when to use the checkboxes component in your service in the [GOV.UK Design System](https://design-system.service.gov.uk/components/checkboxes). ## Quick start examples ### Checkboxes [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/preview) #### Markup
What is your nationality? If you have dual nationality, select all options that are relevant to you.
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "idPrefix": "nationality", "name": "nationality", "fieldset": { "legend": { "text": "What is your nationality?" } }, "hint": { "text": "If you have dual nationality, select all options that are relevant to you." }, "items": [ { "value": "british", "text": "British" }, { "value": "irish", "text": "Irish" }, { "value": "other", "text": "Citizen of another country" } ] }) }} ### Checkboxes with id and name [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-id-and-name/preview) #### Markup
What is your nationality? If you have dual nationality, select all options that are relevant to you.
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "fieldset": { "legend": { "text": "What is your nationality?" } }, "hint": { "text": "If you have dual nationality, select all options that are relevant to you." }, "items": [ { "name": "british", "id": "item_british", "value": "yes", "text": "British" }, { "name": "irish", "id": "item_irish", "value": "irish", "text": "Irish" } ] }) }} ### Checkboxes with hints on items [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-hints-on-items/preview) #### Markup

How do you want to sign in?

You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before.
You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity.
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "fieldset": { "legend": { "text": "How do you want to sign in?", "isPageHeading": true } }, "items": [ { "name": "gateway", "id": "government-gateway", "value": "gov-gateway", "text": "Sign in with Government Gateway", "hint": { "text": "You’ll have a user ID if you’ve registered for Self Assessment or filed a tax return online before." } }, { "name": "verify", "id": "govuk-verify", "value": "gov-verify", "text": "Sign in with GOV.UK Verify", "hint": { "text": "You’ll have an account if you’ve already proved your identity with either Barclays, CitizenSafe, Digidentity, Experian, Post Office, Royal Mail or SecureIdentity." } } ] }) }} ### Checkboxes with disabled item [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-disabled-item/preview) #### Markup
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "name": "colours", "items": [ { "value": "red", "text": "Red" }, { "value": "green", "text": "Green" }, { "value": "blue", "text": "Blue", "disabled": true } ] }) }} ### Checkboxes with legend as a page heading [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-legend-as-a-page-heading/preview) #### Markup

Which types of waste do you transport regularly?

Select all that apply
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "name": "waste", "fieldset": { "legend": { "text": "Which types of waste do you transport regularly?", "classes": "govuk-fieldset__legend--l", "isPageHeading": true } }, "hint": { "text": "Select all that apply" }, "items": [ { "value": "animal", "text": "Waste from animal carcasses" }, { "value": "mines", "text": "Waste from mines or quarries" }, { "value": "farm", "text": "Farm or agricultural waste" } ] }) }} ### Checkboxes with a medium legend [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-a-medium-legend/preview) #### Markup
Which types of waste do you transport regularly? Select all that apply Select which types of waste you transport regularly
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "name": "waste", "fieldset": { "legend": { "text": "Which types of waste do you transport regularly?", "classes": "govuk-fieldset__legend--m" } }, "hint": { "text": "Select all that apply" }, "errorMessage": { "text": "Select which types of waste you transport regularly" }, "items": [ { "value": "animal", "text": "Waste from animal carcasses" }, { "value": "mines", "text": "Waste from mines or quarries" }, { "value": "farm", "text": "Farm or agricultural waste" } ] }) }} ### Checkboxes without fieldset [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/without-fieldset/preview) #### Markup
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "name": "colours", "items": [ { "value": "red", "text": "Red" }, { "value": "green", "text": "Green" }, { "value": "blue", "text": "Blue" } ] }) }} ### Checkboxes with all fieldset attributes [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-all-fieldset-attributes/preview) #### Markup
What is your nationality? If you have dual nationality, select all options that are relevant to you. Please select an option
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "idPrefix": "example", "name": "example", "fieldset": { "classes": "app-fieldset--custom-modifier", "attributes": { "data-attribute": "value", "data-second-attribute": "second-value" }, "legend": { "text": "What is your nationality?" } }, "hint": { "text": "If you have dual nationality, select all options that are relevant to you." }, "errorMessage": { "text": "Please select an option" }, "items": [ { "value": "british", "text": "British" }, { "value": "irish", "text": "Irish" }, { "value": "other", "text": "Citizen of another country" } ] }) }} ### Checkboxes with error message [Preview this example in the Frontend review app](http://govuk-frontend-review.herokuapp.com/components/checkboxes/with-error-message/preview) #### Markup
Which types of waste do you transport regularly? Please select an option
#### Macro {% from "checkboxes/macro.njk" import govukCheckboxes %} {{ govukCheckboxes({ "name": "waste", "errorMessage": { "text": "Please select an option" }, "fieldset": { "legend": { "text": "Which types of waste do you transport regularly?" } }, "items": [ { "value": "animal", "text": "Waste from animal carcasses" }, { "value": "mines", "text": "Waste from mines or quarries" }, { "value": "farm", "text": "Farm or agricultural waste" } ] }) }} ## Requirements ### Build tool configuration When compiling the Sass files you'll need to define includePaths to reference the node_modules directory. Below is a sample configuration using gulp .pipe(sass({ includePaths: 'node_modules/' })) ### Static asset path configuration In order to include the images used in the components, you need to configure your app to show these assets. Below is a sample configuration using Express js: app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/assets'))) ## Component arguments If you are using Nunjucks,then macros take the following arguments **If you’re using Nunjucks macros in production be aware that using `html` arguments, or ones ending with `Html` can be a [security risk](https://en.wikipedia.org/wiki/Cross-site_scripting). More about it in the [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#user-defined-templates-warning).**
Name Type Required Description
fieldset object No Arguments for the fieldset component (e.g. legend). See fieldset component.
hint object No Arguments for the hint component (e.g. text). See hint component.
errorMessage object No Arguments for the errorMessage component (e.g. text). See errorMessage component.
idPrefix string No String to prefix id for each checkbox item if no id is specified on each item. If`idPrefix` is not passed, fallback to using the name attribute instead.
name string Yes Name attribute for each checkbox item.
items array Yes Array of checkbox items objects.
items.{}.text (or) items.{}.html string Yes Text or HTML to use within each checkbox item label. If `html` is provided, the `text` argument will be ignored.
items.{}.id string No Specific id attribute for the checkbox item. If ommited, then `idPrefix` string will be applied.
items.{}.name string Yes Specific name for the checkbox item. If ommited, then component global `name` string will be applied.
items.{}.value string Yes Value for the checkbox input.
items.{}.label object No Provide additional attributes and classes to each checkbox item label. See [label](../label/README.md#component-arguments) component for more details.
items.{}.hint object No Provide optional hint to each checkbox item. See `hint` component for more details.
items.{}.checked boolean No If true, checkbox will be checked.
items.{}.conditional boolean No If true, content provided will be revealed when the item is checked.
items.{}.conditional.html boolean No Provide content for the conditional reveal.
items.{}.disabled boolean No If true, checkbox will be disabled.
classes string No Optional additional classes to add to the checkboxes container.
attributes object No Any extra HTML attributes (for example data attributes) to add to the checkboxes container.
**If you’re using Nunjucks macros in production be aware that using `html` arguments, or ones ending with `Html` can be a [security risk](https://en.wikipedia.org/wiki/Cross-site_scripting). More about it in the [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#user-defined-templates-warning).** ### Setting up Nunjucks views and paths Below is an example setup using express configure views: nunjucks.configure('node_modules/govuk-frontend/components', { autoescape: true, cache: false, express: app }) ## Contribution Guidelines can be found at [on our Github repository.](https://github.com/alphagov/govuk-frontend/blob/master/CONTRIBUTING.md "link to contributing guidelines on our github repository") ## License MIT