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

Loading...

Disabled

Loading...

Help text

Loading...

Error

Loading...

Group

Loading...

Direction

Loading...

Group help text

Loading...

Group error

Loading...

Optional

Loading...

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.

Loading...

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.

Loading...

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