Edit page

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:

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.

Label Options

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

It's also possible to display label before input:

States

Validation States

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

Disabled State

Disabled state makes the input unavailable.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or you can add whatever HTML attribute you like. All attributes that don't interfere with the API are forwarded to the native HTML <input>. This enables making the component interactive and helps to improve its accessibility.

๐Ÿ‘‰ Refer to the MDN reference for the full list of supported attributes of the checkbox input type.

Forwarding ref

If you provide ref, it is forwarded to the native HTML <input> element.

API

Prop nameTypeDefaultRequiredDescription
disabledboolfalsefalse

If true, the input will be disabled.

helpTextnodenullfalse

Optional help text.

idstringundefinedfalse

ID of the <input> HTML element.

Also serves as base for ids of nested elements:

  • <ID>__label
  • <ID>__labelText
  • <ID>__helpText
  • <ID>__validationText
isLabelVisiblebooltruefalse

If false, the label will be visually hidden (but remains accessible by assistive technologies).

labelstringโ€”true

Checkbox field label.

labelPosition'before' โ”‚ 'after''after'false

Placement of the label relative to the input.

requiredboolfalsefalse

If true, the input will be required.

validationState'invalid' โ”‚ 'valid' โ”‚ 'warning'nullfalse

Alter the field to provide feedback based on validation result.

validationTextnodenullfalse

Validation message to be displayed.

Theming

Head to Forms Theming to see shared form theming options. On top of that, the following options are available for CheckboxField.

Custom PropertyDescription
--rui-FormField--check__input--checkbox__border-radiusInput corner radius
--rui-FormField--check__input--checkbox--checked__background-imageBackground image of checked input