Newskit Logo
View Github

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

View code

Status

Supported

Introduced

v4.2.0

Anatomy

The Checkbox contains one required element and three optional elements.

ItemNameDescriptionComponentOptional

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

The Checkbox has a label that appears to the right (end) of a Checkbox.

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

The Checkbox has a label that appears to the right (end) of a Checkbox.

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:

Grouping Checkboxes

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.

Focus order
OrderElementRole
Keyboard Interactions
CommandDescription
WAI-ARIA
ElementAttributeValueDescriptionUser 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.

FormInput Checkbox

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.

NameTypeDefaultDescriptionRequired

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.

Checkbox

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.

NameTypeDefaultDescriptionRequired

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.

FeatureDescriptionStatus

Need Help?

Cant find what you are looking for?

Need Help?

Cant find what you are looking for?