Taxonomic name: A-CHECKBOX
Added on: v3.0.0 (15/09/17)
Updated on: v5.6.1 (26/04/21)

Checkbox

Checkboxes allow users to select none, one or more items from a list of options.

Design and usage

Checkboxes should behave independently from each other.
A single checkbox should be used where a user needs to indicate agreement (for example to terms and conditions).
The checkbox itself, and its container are clickable, to provide a larger target area.
Checkbox labels may wrap to a maximum of two lines.
Checkboxes are displayed in a stacked list in a mobile view.
Aria-invalid must be used to indicate when an error has occurred with this element.
Aria-describedby must be used to link any help, instructional and/or error text with the element/form fields.
Do not use for mutually exclusive options - use radio buttons or drop down lists instead.
Do not use a negative statement for a checkbox label.
Do not place more than 2 pictoral checkboxes next to each other in the same row.

Examples

Standard checkboxes

Interactive example

Code example

	
<fieldset class="m-form-row">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item m-form-row-group-item--full-width">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

columns checkboxes

Interactive example

Code example

	
<fieldset class="m-form-row">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul 
			class="
				m-form-row-group 
				m-form-row-group--option-group 
				m-form-row-group-items--1-small 
				m-form-row-group-items--2-medium 
				m-form-row-group-items--3-large
			"
		>
			<li class="m-form-row-group-item">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Pictorial checkbox control

Inline icon images should be made up as a single sprite with a fixed size of 230px x 74px, with the two versions of the individual icons within it being no more than 85px x 74px and centred horizontally at 50px and 165px.

Interactive example

Code example

	
<fieldset class="m-form-row">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group m-form-row-group--pictorial [ Modifier ]">
			<li class="m-form-row-group-item">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" type="checkbox" name="..." id="..." value="..." />
					<span class="a-checkbox__label">
						<span class="a-checkbox__label-image">
							<img src="..." decoding="async" width="..." height="..." alt="" />
						</span>
						<span class="a-checkbox__label-inner">...</span>
					</span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Agreement confirmation checkbox

Interactive example

Code example

<div class="m-form-row">
	<span class="a-label"></span>
	<div class="m-form-row__content">
		<label class="a-checkbox" for="...">
			<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
			<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
			<span class="a-checkbox__ui"></span>
		</label>
	</div>
</div>

Standalone checkbox variant

Interactive example

Code example

<label class="a-checkbox a-checkbox--standalone" for="...">
	<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
	<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
	<span class="a-checkbox__ui"></span>
</label>

Required standalone checkbox variant

<label class="a-checkbox a-checkbox--standalone" for="...">
	<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." aria-required="true" />
	<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
	<span class="a-checkbox__ui"></span>
</label>

Standalone checkbox group

Interactive example

Code example

<fieldset class="m-form-row">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item m-form-row-group-item--full-width">
				<label class="a-checkbox a-checkbox--standalone" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Checkbox valid

Interactive example

Code example

<fieldset class="m-form-row is-valid">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<p class="m-form-row__validation-message">...</p>
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item m-form-row-group-item--full-width">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Checkbox error

Interactive example

Code example

When help text is present include the help text id along with the error message id within aria-describedby on the fieldset.

<fieldset class="m-form-row is-error" aria-invalid="true" aria-describedby="[ help text id ] [ error message id ]">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<div class="m-show-more" id="..." data-module="m-show-more" data-description="..." data-expand="..." data-contract="...">
			<p>...</p>
			...
		</div>
		<p class="m-form-row__error-message" id="..."><span class="u-hidden--visually">Error: </span>...</p>
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Checkbox disabled

Interactive example

Code example

<fieldset class="m-form-row is-disabled">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item m-form-row-group-item--full-width">
				<label class="a-checkbox" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." disabled />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Individual checkbox disabled

<fieldset class="m-form-row">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group">
			<li class="m-form-row-group-item m-form-row-group-item--full-width">
				<label class="a-checkbox is-disabled" for="...">
					<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." disabled />
					<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
					<span class="a-checkbox__ui"></span>
				</label>
			</li>
			...
		</ul>
	</div>
</fieldset>

Agreement confirmation checkbox errored

Interactive example

Code example

<div class="m-form-row is-error">
	<span class="a-label"></span>
	<div class="m-form-row__content">
		<div class="m-show-more" id="..." data-module="m-show-more" data-description="..." data-expand="..." data-contract="...">
			<p>...</p>
			...
		</div>
		<p class="m-form-row__error-message" id="..."><span class="u-hidden--visually">Error: </span>...</p>
		<label class="a-checkbox" for="...">
			<input class="a-checkbox__input" name="..." id="..." type="checkbox" value="..." aria-invalid="true" aria-describedby="[ help text id ] [ error message id ]" />
			<span class="a-checkbox__label"><span class="a-checkbox__label-inner">...</span></span>
			<span class="a-checkbox__ui"></span>
		</label>
	</div>
</div>

Required checkbox group

<fieldset class="m-form-row" aria-required="true">
	<legend class="a-label">...</legend>
	<div class="m-form-row__content">
		<ul class="m-form-row-group m-form-row-group--option-group [ Modifier ]">
			...
		</ul>
	</div>
</fieldset>

Development and test

Notes for developers

When creating a group of checkboxes they must be contained within their one fieldset where the legend is the question for the group of checkboxes.

Within a group of checkboxes the name attribute must be unique to the form, and the id attribute must be unique to the page.

When disabling form elements, do not solely rely on the is-disabled class, but ensure that the disabled attribute is also set on the relevant form element or input. If an entire set of form elements is to be disabled, the is-disabled class and disabled attribute should be added directly to the fieldset instead, and not to each individual element within it. However if only one element from the set is disabled, then the class and attribute should be applied to that element only.

If the native form validation needs to be disabled, set the novalidate attribute on the form.

When using agreement confirmation checkboxes, never embed hyperlinks into the confirmation copy.

Aria usage for errors and help text

To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.

All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.

All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.

All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.

When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.

Single form field - All attributes should be applied directly to that form field
Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)

There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.

Important messages

To help those using assistive technologies, make sure that success/error messages which need to be announced to users have their aria attributes updated to role="alert" and/or aria-live="assertive".

Using autocomplete

Users appreciate when websites save them time by automatically filling common fields like names, email addresses and other frequently used fields, plus it helps to reduce potential input errors, especially on virtual keyboards and small devices.

Browsers use many methods to determine which fields they can auto-populate based on previously specified data by the user, and you can give hints to the browser by providing both the name attribute and the autocomplete attribute on each input element.

Further details can be found in the developer notes on the form introduction page.

Notes for testers

In this instance the label for the checkbox is the wording directly on the right of the checkbox. Clicking/pressing the explanatory text for the group of checkboxes will not transfer focus to any of the checkboxes like it would for a text input.
The label should be displayed to the right of the checkbox and should activate the checkbox when selected (as should the checkbox itself).
It should be really clear which label applies to which checkbox by using background shading to group the label and the checkbox together.

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

Class	Outcome	Required	Applied to	Comments
`.m-form-row-group`	Base styling for a group of checkboxes	Yes	`.m-form-row__content > ul`
`.m-form-row-group--option-group`	Base styling for a group of checkboxes	Yes	`.m-form-row-group`
`.m-form-row-group--pictorial`	Modifier for the pictorial checkboxes group		`.m-form-row-group`
`.m-form-row-group-items--size-breakpoint`	Modifier to place checkboxes in multiple columns for each breakpoints size: from 1 to 6 breakpoint: small, medium, large		`.m-form-row-group`
`.m-form-row-group-item`	Base for individual checkboxes	Yes	`.m-form-row-group > li`
`.m-form-row-group-item--full-width`	Modifer to force radios to be full width (not natural width) when not in column system	&bnsp;	`.m-form-row-group-item`	Only exclude if using a group of standalone checkboxes
`.a-checkbox`	Additional styles for checkboxes	Yes	`label`
`.a-checkbox--pictorial`	Modifier for a single pictorial checkbox		`.a-checkbox`	Only use if the checkbox is being used on it own if in a group use `.m-form-row-group--pictorial` on the `m-form-row-group`
`.a-checkbox__input`	Additional styles for checkboxes	Yes	`.a-checkbox > input`
`.a-checkbox__label`	Styles for the label	Yes	`.a-checkbox__input + span`
`.a-checkbox__label-image`	Wrapper to mask inline sprite image		`.a-checkbox__label + span`	Place inline image within this wrapper to ensure only selected spite image is visible
`.a-checkbox__label-inner`	Styles in order to keep the label centered when multiple lines are needed	Yes	`.a-checkbox__label > span`
`.a-checkbox__ui`	Animations for the checkbox	Yes	`.a-checkbox__label + span`
`a-checkbox--standalone`	Needed to pull in styling for the standalone checkbox variant		`a-checkbox`
`is-disabled`	To style a disabled row or individual checkbox		`m-form-row` `a-checkbox`

Keyboard operations

TAB: Tabbing to an checkbox input should make the input clearly visually different so that the focus point on the page is obvious to the user.
CURSOR KEYS: With focus on the checkbox, pressing SPACE will select/de-select the checkbox.

Component releases

Added on: v3.0.0 (15/09/17)
Updated on: DESY HTML v.2023.01 (14/04/23)

Latest update:

fixed: Positioning for pictorial checkbox sprites has been updated.

Full version history

A full history of changes and enhancements detailing all minor and major updates to the component.

View full version history

Want something new in Framework, or to chat about an issue you're having with it?

Contact the team