React UI
Edit page
Home
Getting Started
Customize
Foundation
Components: UI
Alert Badge Button ButtonGroup Card CheckboxField
Basic Usage General Guidelines Help Text Label Options States API Modal Radio ScrollView SelectField Table TextArea TextField Toggle
Components: Layouts
CSS Helpers
Readme

# CheckboxField

CheckboxField allows users to select one or more options from a set.

##
Basic Usage

To implement the CheckboxField component, you need to import it first:

    import { CheckboxField } from '@react-ui-org/react-ui';

And use it:

I agree
() => { const [agree, setAgree] = React.useState(true) return ( <CheckboxField changeHandler={() => setAgree(!agree)} checked={agree} id="my-checkbox" label="I agree" /> ) }

    () => {  const [agree, setAgree] = React.useState(true)  return (    <CheckboxField      changeHandler={() => setAgree(!agree)}      checked={agree}      id="my-checkbox"      label="I agree"    />  )}

See
API for all available options.

## General Guidelines

- Use the CheckboxField when there are lists of options and the user may
  select any number of choices, including zero, one, or several. For selecting just a single option from the list, use either the Radio or SelectField component.

- Use the CheckboxField for boolean (true/false) input in forms that require to be confirmed by a button to become active. To toggle things on or off with an immediate effect (without confirmation), use rather the Toggle component.

- Use positive wording for the checkbox label, so that it's clear what will happen when the user turns on the checkbox. Avoid negations such as “Don't send me any emails” which would mean that the user needs to turn the checkbox on in order for something not to happen.

- Only make the CheckboxField's label invisible when there is another visual clue to guide users through toggling the input.

- When a short label is not enough, use help texts to guide users before they enter anything.

- Use clear, calm error messages when there's a problem with what they entered.

- Visually present groups of choices as groups, and clearly separate them from other groups on the same page.

📖 Read more about checkboxes and radios at Nielsen Norman Group.

## Help Text

You may provide an additional help text to clarify what will be the impact of turning the checkbox on or off.

Send me newsletter
We will not bother you more than once a month, we promise!
() => { const [getNewsletter, setGetNewsletter] = React.useState(true) return ( <CheckboxField changeHandler={() => setGetNewsletter(!getNewsletter)} checked={getNewsletter} description="We will not bother you more than once a month, we promise!" id="my-checkbox-with-helper-text" label="Send me newsletter" /> ) }

    () => {  const [getNewsletter, setGetNewsletter] = React.useState(true)  return (    <CheckboxField      changeHandler={() => setGetNewsletter(!getNewsletter)}      checked={getNewsletter}      description="We will not bother you more than once a month, we promise!"      id="my-checkbox-with-helper-text"      label="Send me newsletter"    />  )}

## Label Options

In some cases, it may be convenient to visually hide the checkbox label. The label remains accessible to assistive technologies.

You cannot see this
() => { const [checked, setChecked] = React.useState(true) return ( <CheckboxField changeHandler={() => setChecked(!checked)} checked={checked} id="my-checkbox-with-invisible-label" isLabelVisible={false} label="You cannot see this" /> ) }

    () => {  const [checked, setChecked] = React.useState(true)  return (    <CheckboxField      changeHandler={() => setChecked(!checked)}      checked={checked}      id="my-checkbox-with-invisible-label"      isLabelVisible={false}      label="You cannot see this"    />  )}

It's also possible to display the label before the input:

The label precedes the input
() => { const [checked, setChecked] = React.useState(true) return ( <CheckboxField changeHandler={() => setChecked(!checked)} checked={checked} id="my-checkbox-with-label-before-input" label="The label precedes the input" labelPosition="before" /> ) }

    () => {  const [checked, setChecked] = React.useState(true)  return (    <CheckboxField      changeHandler={() => setChecked(!checked)}      checked={checked}      id="my-checkbox-with-label-before-input"      label="The label precedes the input"      labelPosition="before"    />  )}

## States

### Validation States

Validation states visually present the result of validation of the input. You should always provide a help text for states other than valid so users know what happened and what action they should take or what options they have.

I agree
I agree
Please wait 10 minutes until we verify your data.
I agree
You must agree to be able to proceed.
() => { const [agree, setAgree] = React.useState(true) return ( <> <CheckboxField changeHandler={() => setAgree(!agree)} checked={agree} id="my-checkbox-valid" label="I agree" validationState="valid" /> <CheckboxField changeHandler={() => setAgree(!agree)} checked={agree} description="Please wait 10 minutes until we verify your data." id="my-checkbox-warning" label="I agree" validationState="warning" /> <CheckboxField changeHandler={() => setAgree(!agree)} checked={agree} error="You must agree to be able to proceed." id="my-checkbox-invalid" label="I agree" required validationState="invalid" /> </> ) }

    () => {  const [agree, setAgree] = React.useState(true)  return (    <>      <CheckboxField        changeHandler={() => setAgree(!agree)}        checked={agree}        id="my-checkbox-valid"        label="I agree"        validationState="valid"      />      <CheckboxField        changeHandler={() => setAgree(!agree)}        checked={agree}        description="Please wait 10 minutes until we verify your data."        id="my-checkbox-warning"        label="I agree"        validationState="warning"      />      <CheckboxField        changeHandler={() => setAgree(!agree)}        checked={agree}        error="You must agree to be able to proceed."        id="my-checkbox-invalid"        label="I agree"        required        validationState="invalid"      />    </>  )}

### Disabled State

Disabled state makes the input unavailable.

Disabled checkbox
Disabled checkbox, checked
<CheckboxField label="Disabled checkbox" id="my-checkbox-disabled" disabled /> <CheckboxField label="Disabled checkbox, checked" id="my-checkbox-checked-disabled" disabled checked />

    <CheckboxField label="Disabled checkbox" id="my-checkbox-disabled" disabled /><CheckboxField  label="Disabled checkbox, checked"  id="my-checkbox-checked-disabled"  disabled  checked/>

## API

In addition to the options below, you can add any custom attributes that do not interfere with the API, and they will be passed to the
`input` HTML element. This is useful mainly to improve component's accessibility.

changeHandler
func
null
checked
bool
false
description
string
null
disabled
bool
false
error
string
null
forwardedRef
Function │ { "current": "any" }
undefined
id
string
required
inFormLayout
bool
false
isLabelVisible
bool
true
label
string
required
labelPosition
'before' │ 'after'
'after'
layout
'horizontal' │ 'vertical'
'vertical'
required
bool
false
validationState
'invalid' │ 'valid' │ 'warning'
null
value
string │ number
undefined

Next: Modal →