Checkbox

What is this?

Checkboxes are tools that customize configurations. This control has three states: checked, unchecked and indeterminate. They reflect the selection of an option and its execution usually requires another control, or confirmation.

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 just need to pass the hook return object to the checkboxes 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'll need to combine the checkbox tri-state: checked, not checked, 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 the filed is 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 filed is 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 state	-	-

Accessibility

• Checkbox has role checkbox.
• When checked, Checkbox has aria-checked set to true.
• When not checked, Checkbox has aria-checked set to false.
• When partially checked, Checkbox has aria-checked set to mixed.

Do’s

1. Settings confirmation, that require an additional action to activate.
2. Multiple choices.
3. Undetermined state, when multiple sub-options are grouped under a parent option.
4. Clear visual state for selected and unselected options.
5. List of related items.
6. Binary options are available, like yes/no choices.
7. Use titles to group related controls.
8. Choose words that are aligned with our ecommerce vocabulary.
9. Write the current state of the control, to improve accessibility.
10. Add descriptions if the control is critical, or complex.
11. Lists of controls should be vertical for better scannability

👉 For UX Writing guidelines, access https://uxwriting.vtex.com

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