Actions & Inputs
Checkbox
Checkboxes are selection controls that allow users to select one or multiple items from a group of options. They typically appear in forms.
Status
Supported
Introduced
v4.2.0
Status
Supported
Introduced
v4.2.0
Anatomy
The Checkbox contains one required element and three optional elements.
| Item | Name | Description | Component | Optional |
|---|
Options
The Checkbox has options that can be used to provide an appropriate experience for different use cases.
Size
There are three sizes of Checkbox input and the feedback element; small, medium (default), and large.
The icon that appears within the Checkbox input remains the same size at all three sizes but can be overridden.
Icon
The icon that appears within the Checkbox input can be overridden for the different Checkbox states.
Feedback
The feedback element is non-interactive and appears in the background behind the Checkbox input for visual feedback on hover.
Label
In the case of needing a label on the left (start) of a Checkbox, this can be set via the labelPosition prop.
Fieldset
Selection controls (inputs), such as the FormInput, Radio Button, and Checkbox, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.
The Fieldset can also support other selection controls (inputs) such as the FormInput, FormInput Switch, and FormInput TextField.
For more information, please refer to the Fieldset component.
Size
There are three sizes of Checkbox input and the feedback element; small, medium (default), and large.
The icon that appears within the Checkbox input remains the same size at all three sizes but can be overridden.
Icon
The icon that appears within the Checkbox input can be overridden for the different Checkbox states.
Feedback
The feedback element is non-interactive and appears in the background behind the Checkbox input for visual feedback on hover.
Label
In the case of needing a label on the left (start) of a Checkbox, this can be set via the labelPosition prop.
Fieldset
Selection controls (inputs), such as the FormInput, Radio Button, and Checkbox, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.
The Fieldset can also support other selection controls (inputs) such as the FormInput, FormInput Switch, and FormInput TextField.
For more information, please refer to the Fieldset component.
States
The Checkbox has the following states:
Base
The Checkbox has a base (default) state. This is the base style of the Checkbox before it has been interacted with by a user.
Hover
The Checkbox has a hover state. The style of the Checkbox changes to visually communicate and provide feedback to the user that the Checkbox is an interactive element. The style of the label remains the same. The label can also be interacted with (hovered) to check the Checkbox.
Focus
The Checkbox in a focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Focus Hover
The Checkbox in a focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked
The Checkbox has a checked state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked. The style of the label remains the same.
Checked Hover
The Checkbox has a checked hover state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked and hovered over. The style of the label remains the same.
Checked Focus
The Checkbox in a checked focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked Focus Hover
The Checkbox in a checked focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Invalid
The Checkbox in an invalid state changes style when the Checkbox selection doesn’t conform to a specific format eg. attempting to proceed without selecting a required Checkbox in a Form. The Form component is used to apply validation behaviour. The style of the label remains the same.
Invalid Focus
The Checkbox in an invalid focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Invalid Hover
The Checkbox has an invalid hover state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox is in an invalid state and hovered over. The style of the label remains the same.
Invalid Focus Hover
The Checkbox in an invalid focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked Invalid
The Checkbox has a checked invalid state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked and is in an invalid state. The style of the label remains the same.
Checked Invalid Focus
The Checkbox in a checked invalid focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked Invalid Hover
The Checkbox has a checked invalid hover state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked and is in an invalid state, and hovered over. The style of the label remains the same.
Checked Invalid Focus Hover
The Checkbox in a checked invalid focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Valid
The Checkbox in an valid state changes style when the Checkbox selection conforms to a specific format eg.updating preferences in a Form. The Form component is used to apply validation behaviour.The style of the label remains the same.
Valid Focus
The Checkbox in a valid focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Valid Hover
The Checkbox has a valid hover state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox is in a valid state and hovered over. The style of the label remains the same.
Valid Focus Hover
The Checkbox in a valid focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked Valid
The Checkbox has a checked valid state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked and is in a valid state. The style of the label remains the same.
Checked Valid Focus
The Checkbox in a checked valid focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Checked Valid Hover
The Checkbox has a checked valid hover state. The style of the Checkbox input changes to visually communicate and provide feedback to the user that the Checkbox has been checked and is in a valid state, and hovered over. The style of the label remains the same.
Checked Valid Focus Hover
The Checkbox in a checked valid focus hover state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.
Disabled
The Checkbox in a disabled state communicates that a Checkbox exists, but is not available to the user in that scenario. When the user's cursor hovers over a Checkbox in a disabled state, the cursor shows as not allowed.
Disabled Checkboxes are often used to maintain layout consistency and communicate that a Checkbox may become available if another condition has been met. The style of the label (colour) also changes to indicate that the Checkbox is disabled.
Checked Disabled
The Checkbox in a checked disabled state communicates that a Checkbox exists, but is not available to the user in that scenario. When the user's cursor hovers over a Checkbox in a checked disabled state, the cursor shows as not allowed.
Disabled checked Checkboxes are often used to maintain layout consistency and communicate that a Checkbox may become available if another condition has been met. The style of the label (colour) also changes to indicate that the Checkbox is checked and disabled.
The Feedback element becomes visible (configurable) on state change, eg hover.
Behaviours
The following guidance describes how the Checkbox component behaves.
Checked vs unchecked
Checkboxes can be checked or unchecked. A Checkbox in a checked state is indicated with an icon that appears in the centre of the checkbox.
Label overflow wrap
When a Label is too long for the available horizontal space, it wraps to form another line.
Transition
When the Checkbox is checked, the ‘check’ icon fades up in the centre of the Checkbox, and the backgroundColor, and borderColor transition simultaneously.
Clickable area
The Checkbox feedback element indicates the minimum clickable area for the Checkbox input (also known as hit area, or touch target area). The size of the clickable area changes according to the size of the Checkbox. The associated Label is also clickable next to the Checkbox.
Focusable area
Both the Checkbox input and Label are interactive, and a user can hover over either, but only the Checkbox input itself is focusable by using an input method such as a keyboard or voice.
Validation
The Checkbox validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.
For more information, please refer to the Form component.
Note
Validation only works if the FormInput Checkbox uses the Form component.
Autofocus
The Checkbox can be set to be auto-focused on page load (when mounted).
Default checked
The Checkbox initial state can be set to be checked or unchecked by default (controlled or uncontrolled).
Checked vs unchecked
Checkboxes can be checked or unchecked. A Checkbox in a checked state is indicated with an icon that appears in the centre of the checkbox.
Label overflow wrap
When a Label is too long for the available horizontal space, it wraps to form another line.
Transition
When the Checkbox is checked, the ‘check’ icon fades up in the centre of the Checkbox, and the backgroundColor, and borderColor transition simultaneously.
Clickable area
The Checkbox feedback element indicates the minimum clickable area for the Checkbox input (also known as hit area, or touch target area). The size of the clickable area changes according to the size of the Checkbox. The associated Label is also clickable next to the Checkbox.
Focusable area
Both the Checkbox input and Label are interactive, and a user can hover over either, but only the Checkbox input itself is focusable by using an input method such as a keyboard or voice.
Validation
The Checkbox validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.
For more information, please refer to the Form component.
Note
Validation only works if the FormInput Checkbox uses the Form component.
Autofocus
The Checkbox can be set to be auto-focused on page load (when mounted).
Default checked
The Checkbox initial state can be set to be checked or unchecked by default (controlled or uncontrolled).
Usage
The following guidance describes how and when to appropriately use the Checkbox component.
Do
Group Checkboxes along with other selection controls, Labels, and Assistive Text together with the Fieldset component and the Legend that gives a title attributed to the elements that appear in the Fieldset.
Do
When medium or large Checkboxes are too visually prominent, small checkboxes can work well on information dense screens/pages.
For example, smaller checkboxes may let users see more options in a form at a glance.
Do
Checkboxes should be used to help users select multiple options from a list or to check or uncheck a single option. Unlike Radios, users can select multiple options from a list of Checkboxes.
Don’t
Avoid using the Checkbox component if users can only choose one option from a selection. In this case, use the Radio Button component.
Do
Checkboxes should always have a Label associated to give users context of what the Checkbox represents.
Don’t
Avoid placing Labels to the left (start) of Checkboxes when there are multiple Checkboxes grouped together to avoid layout misalignment. Instead place Labels to the right (end) so that when used together in forms, Checkbox inputs align vertically, which makes them easier to find, especially for users of screen magnifiers.
Do
Checkboxes should be displayed vertically, stacked for consistent alignment and positioning across different breakpoints.
Don’t
Avoid using Checkboxes in a horizontal orientation to avoid issues with alignment and legibility when there are multiple Checkboxes grouped together.
Do
If needed Assistive Text should be used to hint at the action the user is being asked to do, for example, ‘Select all that apply’.
Don’t
Avoid default checked options where possible as this makes it more likely that users will not realise they’ve missed a question, or submit the wrong answer when not intended.
Do
Swap Assistive Text with error text if the Checkbox is invalid. Once the Checkbox is valid then the assistive is then shown again.
Do
Write error text that communicates a solution. Error text should be written in no more than a few clear, concise and complete sentences.
Accessibility Considerations
The Checkbox has the following accessibility considerations:
It is recommended to group Checkboxes and other related elements such as Labels and Assistive Text together using the Fieldset component, with a title attributed to the elements that appear in the Fieldset, called a Legend.
| Order | Element | Role |
|---|
| Command | Description |
|---|
| Element | Attribute | Value | Description | User Supplied |
|---|
API
The Checkbox has a range of props that can be used to define an appropriate experience for different use cases.
There are two components exported from the package, one for use within the NewsKit Form component, and one for use as a controlled component.
The FormInput Checkbox has a range of props that can be used to define an appropriate experience for different use cases.Use this component within the NewsKit Form component.
| Name | Type | Default | Description | Required |
|---|
Note
The name & rules props are set on the form input level. If you want to add validation rules or set the name of this component, please refer to the Form component
Note
Engineer to check the validation related props at the time of implementation.
The Checkbox has a range of props that can be used to define an appropriate experience for different use cases. Use this component as a controlled component, for instance where you have a custom validation mechanism.
| Name | Type | Default | Description | Required |
|---|
Compliance
All of the components in the NewsKit design system go through a comprehensive set of checks to ensure that we are producing compliant and best practice components.
| Feature | Description | Status |
|---|