Checkbox

A checkbox allows the user to check or uncheck an option.

Anatomy

The anatomy for both the standalone checkbox and a group of related checkboxes are outlined here.

Checkbox

1. Control - the input control that conveys the current state of the checkbox to the user.
2. Label - a short name that lets the user know what the checkbox is checking. Clicking the label should toggle the checkbox.
3. Description (optional) - additional text that can be used to add clarity or context to the checkbox label. Clicking the description should do nothing.

Checkbox Group

1. Label - text that conveys how the checkboxes are related and prompts the user to check one or more checkbox.
2. Current selection: a checked checkbox indicates that it will be included when the field is submitted.
3. Choices - the available checkboxes. Clicking a checkbox will check or uncheck it.

Usage

• A single checkbox has two mutually exclusive states: checked or unchecked.
• Space toggles the state of the checkbox.
• Use a group of checkboxes to allow a user to check zero, one or multiple options from a list, and display all available options.
• Checkboxes may allow users to sub-select options from a nested list (see tri-state checkboxes).
• Checkboxes work independently of other checkboxes, unless they are controlled by a tri-state checkbox.
• Avoid setting default options, because pre-checking an option makes it more likely that users will not make a conscious choice and submit an option unintentionally.
• Consider the most logical order to list options. Options may be listed alphabetically, by popularity, or some other ordered system that should be clear to the user.

Do

• Do allow users to check an option by clicking the checkbox or its label.
• Do position the checkbox to the left of its label.
• Do separate groups of checkboxes with group labels.
• Do display options in a vertical layout for easier scanning.
• Do define a label for the checkbox, even if it is not visible (example: when checking a row in a table).

Don't

• Don’t use checkboxes if only one item can be checked from a list. Use radio buttons or a dropdown instead.
• Don’t use a checkbox if an action will take immediate effect when the user checks or unchecks it. Add a Submit button to confirm, or use a toggle instead.
• Don’t use negative statements for a checkbox, because taking action to check it is confusing and counter-intuitive. (example: “I don’t want to receive email…”)

Tri-state Checkbox

A tri-state checkbox can be used to represent and control the state of a group of other checkboxes. This type of checkbox adds an "indeterminate" state that conveys to the user that some—but not all—of the related checkboxes are checked.

• If all options in the group are checked, the tri-state checkbox displays as checked.
• If some of the options in the group are checked, the tri-state checkbox displays as indeterminate (partially checked).
• If none of the options in the group are checked, the tri-state checkbox displays as unchecked.
• If a user checks a tri-state checkbox, then all the options in the group are checked.
• If a user unchecks a tri-state checkbox, then all the options in the group are unchecked.

React API

import { Checkbox, CheckboxGroup } from '@wwnds/react';

Checkbox

A single checkbox component.

Live Editor

<Checkbox
	description="Additional information about this checkbox."
	required
	requiredIndicator
>
	Checkbox
</Checkbox>

Result

Loading...

Name	Description	Type
baseName	The base class name according to BEM conventions.	string
description	An optional description. Use this in place of placeholder text or as help text for your field control.	ReactNode
labelClass	A className for the label element, which will be a <label> if htmlFor is included and a <div> otherwise.	string
descriptionClass	A className for the description <div>.	string
labelId	An id for the label element.	string
descriptionId	An id for the description <div>.	string
errors	A list of error strings. If provided, this will be set as an unordered list in the first child slot.	string[]
validators	A list of validators. A validator contains a function that tests the value for validity and a corresponding message that conveys why the test failed.	ValidatorEntry[]
validateOnDOMChange	Indicates that validation should occur when the DOM's change event is triggered. Note that this event is different from React's onChange callback, which triggers on the DOM's input event. Reference: MDN - change event	boolean
validateOnChange	Indicates that validation should occur when onChange is triggered. Alias of validateOnInput.	boolean
maxLengthRestrictsInput	Indicates that a maxLength value should prevent input beyond the maxLength.	boolean
onDOMChange	A callback that will be triggered any time the DOM's change event is triggered. Note that this event is different from React's onChange event, which triggers on the DOM's input event. Reference: MDN - change event MDN - input event	((e: Event) => void)
onValidate	A callback that will be triggered any time the input is validated. See related validators, validateOnChange, and validateOnChange.	((errors: string[]) => void)
indeterminate	Mark the checkbox as indeterminate. Has no effect when type="radio". Reference: DOM - indeterminate MDN - indeterminate	boolean
requiredIndicator	Indicates that the indicator should be "required" when required=true.	boolean
optionalIndicator	Indicates that the indicator should be "optional" when required=false.	boolean
thumbnail	The thumbnail element.	ReactNode
controlClass	The className for the control that sighted users will see.	string
inputClass	The className for the Checkbox's <input> element.	string
thumbnailClass	The className for the Checkbox's thumbnail element.	string
checkedClass	A className that will be applied to the root of the component when it is checked.	string
errorsClass	A className for the error list.	string
errorsId	An id for the error list.	string

CheckboxGroup

A container for a set of related Checkbox components and its associated prompt (label).

Live Editor

<CheckboxGroup label="Select your favorite fruits." name="fruit">
	<Checkbox thumbnail="🍎" description="A classic choice">Apple</Checkbox>
	<Checkbox thumbnail="🍌" description="A taste of the tropics">Banana</Checkbox>
	<Checkbox thumbnail="🥝" description="A bit more exotic">Kiwi</Checkbox>
	<Checkbox thumbnail="🍊" description="Tangy and juicy">Orange</Checkbox>
</CheckboxGroup>

Result

Loading...

Name	Description	Type
label (required)	Text that conveys how the choices are related and prompts the user to choose one or more choice.	ReactNode
name	The name that will be assigned to all child <input> elements.	string
baseName	The base class name according to BEM conventions.	string
description	An optional description. Use this in place of placeholder text or as help text for your field control.	ReactNode
labelClass	A className for the label element, which will be a <label> if htmlFor is included and a <div> otherwise.	string
descriptionClass	A className for the description <div>.	string
labelId	An id for the label element.	string
descriptionId	An id for the description <div>.	string
required	Indicates whether a selection must be made or not.	boolean
errors	A list of error strings. If provided, this will be set as an unordered list in the first child slot.	string[]
requiredIndicator	Indicates that the indicator should be "required" when required=true.	boolean
optionalIndicator	Indicates that the indicator should be "optional" when required=false.	boolean
errorsClass	A className for the error list.	string
errorsId	An id for the error list.	string
fieldName	The name that will be assigned to the parent <fieldset>.	string
choiceClass	The class name that will be used on all Choice elements.	string