Checkbox

What is this?

Checkbox controls allow merchants to make multiple independent choices in a form where there are at most five options and each option is binary.

States

Unchecked

Checked

Indeterminate

Disabled

Unchecked

Checked

Indeterminate

Help text

Checkbox

Help text

Error

Checkbox

Help textError text

Group

Fruits

Apple

Orange

Watermelon

Direction

Fruits

Apple

Orange

Watermelon

Group help text

Fruits

Apple

Orange

Watermelon

Group help text

Group error

Fruits

Apple

Orange

Watermelon

Group error text

Optional

Fruits (optional)

Apple

Orange

Watermelon

Group state

To render multiple checkboxes and store the checked values in an array, you need to pass the hook return object to the checkbox's `state` property and define a unique value for each Checkbox.

Fruits

Apple

Orange

Watermelon

Selected checkboxes:

Group indeterminate state

To implement a checkbox that controls the state of a set of checkboxes you will need to combine the checkbox's three states: checked, unchecked, and indeterminate.

Fruits

Select All (Group Control)

Apple

Orange

Watermelon

Usage

import { Checkbox, CheckboxGroup, useCheckboxState } from '@vtex/admin-ui'

function Example() {
  const state = useCheckboxState({ initialValue: [] })

  return (
    <CheckboxGroup label="Group label">
      <Checkbox label="Label" value="checkbox 1" state={state} />
      <Checkbox label="Label" value="checkbox 2" state={state} />
      <Checkbox label="Label" value="checkbox 3" state={state} />
    </CheckboxGroup>
  )
}

Checkbox props

Name	Type	Description	Required	Default
id	string	Same as the HTML attribute	🚫	-
label	string	Checkbox label	✅	-
value	string, or number	Checkbox value	✅	-
disabled	boolean	Whether Checkbox is disabled or not	🚫	false
checked	boolean	Same as the HTML checked attribute	🚫	-
helpText	ReactNode	Help text	🚫	-
errorText	ReactNode	Error text	🚫	-
error	boolean	Whether there is an error or not	🚫	false
state	CheckboxState	Return of useCheckboxState hook	🚫	-
csx	StyleProp	Defines component styles	🚫	{}

CheckboxGroup props

Name	Type	Description	Required	Default
label	string	Group label	✅	-
helpText	ReactNode	Help text	🚫	-
errorText	ReactNode	Error text	🚫	-
error	boolean	Whether the there is an error or not	🚫	false
direction	row, column	Direction which the children are displayed	🚫	row
optional	boolean	Whether the field is optional or not	🚫	-
csx	StyleProp	Defines component styles	🚫	{}

useCheckboxState

Params props

Name	Type	Description	Required	Default
initialValue	boolean, "indeterminate", any[]	Stores the state of the checkbox. If checkboxes that share this state have a value prop defined, it will be an array.	✅	-

Return props

Name	Type	Description	Required	Default
value	boolean, "indeterminate", any[]	Stores the state of the checkbox. If checkboxes that share this state have a value prop defined, it will be an array.	-	-
setValue	SetStateAction< CheckboxState["value"] >	Sets the checkbox's state	-	-

Accessibility

• Checkbox has the checkbox role.
• When checked, Checkbox has aria-checked set to true.
• When unchecked, Checkbox has aria-checked set to false.
• When indeterminate, Checkbox has aria-checked set to mixed.

Components

When to use the Switch, Radio, or Combobox Multiple components instead of the Checkbox component?

• Choose the Switch component if the action is instant and does not require confirmation. For example, use a Switch in a User Settings page for the option to Activate notifications.
• Choose the Radio component if only one option can be selected at a time and there are up to five options.
• Choose the Combobox Multiple component if multiple options can be selected and there are more than five available options.

When to use a Checkbox Group instead of a Checkbox?

Since the Checkbox label should only correspond to its value, the choice should be contextualized using the label of a Checkbox Group or the title of a form section. This is why the Checkbox Group is usually the right choice even for binary choices where there is only a single Checkbox.

When to use a vertical or a horizontal Checkbox Group?

It is more scalable to distribute options in a vertical direction. Only distribute horizontally if — considering localization — all their labels fit in a single line, have up to 20 characters and don’t vary a lot in length.

Position

How should a Checkbox component be positioned in a form?

Prefer placing a Checkbox at the start or end of a form section.

Behavior

When should a Checkbox be disabled?

• Use a disabled Checkbox only if in some condition it becomes enabled. Example: when an option is incompatible with another option in a form.
• Use a tooltip trigger to explain why the Checkbox is disabled. Display the information when hovering over the tooltip trigger — not the Checkbox itself.

When should the indeterminate state be used?

In scenarios where it might be necessary to check or uncheck all options, a Checkbox can be placed in the beginning of the group with the Select all label. Make sure options below are nested and vertically aligned with the Select all label.

The indeterminate state should be displayed in these scenarios when only a few options (not all) are checked. When clicking the indeterminate state, all options must be checked. When clicking for a second time, all options must be unchecked.

What should be the default value of a Checkbox?

• Preselect an option when this can make the merchant more efficient and when it isn’t important for the choice to be conscious.
• Common or recommended options can be preselected. Information that the merchant has previously provided can be preselected to indicate the option that should be chosen.
• When a recommended option is preselected, add (Recommended) to the end of its label so it can still be identified after edits.

Content

What should be the label of a Checkbox?

• Write the label so it corresponds to the value of the Checkbox.
• Use sentence case but capitalize proper nouns.

What to avoid:

• Don't write long Checkbox labels. Use the help text or the Checkbox Group label to provide additional context when necessary.
• Don't write Checkbox labels that vary a lot in length between options.
• Don't use personal pronouns. For example, write Receive promotional emails instead of I want to receive emails.
• Don't include redundant words. For example, use only S, M, and L instead of Size S, Size M, and Size L.
• Don't include negative words. For example, write Receive promotional emails instead of I don't want to receive emails.

What should be the label of a Checkbox Group?

• Include the name of the entity that is being listed. For example, use the label Fruits when the options are Apple, Orange and Banana.
• Visually hide the label of the Checkbox Group when the form section title already contains the name of the entity that is being listed.
• Use sentence case, but capitalize proper nouns.

What to avoid:

• Don't include redundant words. For example, don't use Product characteristics as the label for a Checkbox Group inside a form page that includes Product in its title – use only Characteristics.
• Don't use verbs. For example, instead of Select characteristics, use only Characteristics.
• Don't use interrogations.

What should be the help text of a Checkbox?

• Include a help text only for critical choices where the consequences of checking the option need to be explained in more detail.
• Write the help text as if you are completing the following sentence: If you check this option, you or the system will [help text].
• Start with verbs in the simple present tense. For example, for the value Fragile the help text should be Prints this information on the shipping label and not Print this information on the shipping label.
• Use sentence case, but capitalize proper nouns.

What to avoid:

• Don't include links. Use an alert component if this is necessary.
• Don't write more than one sentence.
• Don't use periods or commas.

What should be the error text of a Checkbox or a Checkbox Group?

• Prevent errors whenever possible. When an option is checked, disable other incompatible fields or options automatically.
• In a Checkbox Group, if at least one option needs to be checked and none is checked by the merchant, the error text should be Check at least one option.
• Use the imperative form. For example, write Check at least one option instead of At least one option needs to be checked.

What to avoid:

• Don't use periods or commas.
• Don't use incomplete sentences. For example, write Check at least one option instead of Check at least one.

• What is this?
• States
• Disabled
• Help text
• Error
• Group
• Direction
• Group help text
• Group error
• Optional
• Group state
• Group indeterminate state