Checkbox

Checkboxes provide a single binary (yes/no) input field which can be required. Checkbox groups can be used for multiple choice selections.

Code

Installation

yarn add @twilio-labs/match formik

Checkbox Usage

import { Formik } from "formik";
import { Checkbox } from "@twilio-labs/match/components";
const Component = () => (
<Formik
initialValues={{
accept_terms: [],
}}
onSubmit={() => {}}
>
<Checkbox
name="accept_terms"
value="1"
label="Do you accept the terms of service?"
required
/>
</Formik>
);

Note: The value will always be an array, even when working with a single checkbox

CheckboxGroup Usage

import { Formik } from "formik";
import { Checkbox, CheckboxGroup } from "@twilio-labs/match/components";
const Component = () => (
<Formik
initialValues={{
animals: [],
}}
onSubmit={() => {}}
>
<CheckboxGroup
label="What animals do you like?"
additional="Please select at least one option"
required
>
<Checkbox name="animals" value="dog" label="Dogs" />
<Checkbox name="animals" value="cat" label="Cats" />
<Checkbox name="animals" value="rabbit" label="Rabbits" />
<Checkbox name="animals" value="frog" label="Frogs" />
</CheckboxGroup>
</Formik>
);

Checkbox Props

PropTypeDefaultDescription
namestringnull
valuestringnull
labelstringnullLabel for the input element.
required?booleannullRequires input to be checked.
size?CheckboxSize'normal''normal', 'small'
disabled?booleannullDisables the checkbox.
readOnly?booleannullSets the checkbox as readonly
additional?stringnullSupporting information.
validate?(value: string[]) => stringOverrides built in validation.
noValidate?booleannullDisables built in validation.

Also supports margin props.

CheckboxGroup Props

PropTypeDefaultDescription
horizontal?booleannullDisplay checkboxes horizontally.
labelstringnullLabel for the fieldgroup element.
additional?stringnullSupporting information.
size?CheckboxSizenull'normal', 'small'
disabled?booleannullDisables all checkboxes
readOnly?boolean(value: string[]) => stringOverrides built in validation.
noValidate?booleannullDisables built in validation

Also supports margin props.


Guidelines

About Inputs

Checkboxes can be used independently or within a CheckboxGroup with multiple options. If you intend to have multiple options with only one available selection, use a RadioGroup instead.

Accessibility

  • Checkboxes and CheckboxGroups should be described with label props.
  • Use additional text to provide extra context when needed.
  • Keep labels and additional text brief and descriptive for users using assistive technology, so they can understand the question clearly.

Composition

  • Use CheckboxGroup components to group multiple related choices.

  • Checkboxes must have both name and value props.

  • Checkboxes within a checkbox group may have different name props.

Do
  • Use checkboxes in a checkbox group with at least two or more choices - where a user may select more than one option.
  • List options in a logical order that makes sense to your users such as in order of the most common selections or in numerical order.
  • Consider using the multi-select component when list options exceed around 10 choices.
Don't
  • Don't use a single checkbox within a checkbox group.
  • Don't randomize the list options in a way that users will find confusing.
  • Don't have a long list of checkboxes that may overwhelm users.

Examples

Individual Checkbox

Individual checkboxes require name, value, and label props.

Vertical Checkbox Group

The default Checkbox Group style is vertically stacked. This style of Checkbox Group works well for longer content.

Horizontal Checkbox Group

The horizontal prop can be used to give the CheckboxGroup a horizontal layout. This is best for closely related groups with few options. Be mindful of the width of the group, as wrapping may occur.

Readonly

The readOnly prop can be used for displaying selections back to the user.

Disabled

The disabled prop can be used for disallowing user input. Note: Disabled fields are not submitted with the form data.

Required

An error will be displayed if a choice is not selected.

Validation

The default validation can be overridden using the validate prop. Validation can be turned off using the noValidate prop.