Checkbox
Checkboxes are used to choose one or more items from a list. A checkbox can also be used to toggle an option.
Demo
<Checkbox checked label="Checked Checkbox" />
Usage
When to use
- Choose one or more items from a list of choices. Use checkboxes when more than one option can be chosen.
- Toggle an option. A single checkbox can be used as a toggle, to enable or disable a feature, for example.
When not to use
- Choosing a single item. Don't use checkboxes if only one option can be chosen. Use a
Radio
instead. - Choosing from many items. Don't use checkboxes if there are many items to choose from. 7–10 checkboxes is an upper limit. If there's more choices than this, use a
MultiSelect
instead.
Format
Content
- Checkbox labels should be positive, so that checking a checkbox means the option is on or true. So, a checkbox label would read Show legend key, not Hide legend key.
- Always show a label with a checkbox.
Size
Demo
<Checkbox checked dense label="Dense Checked Checkbox" />
- Checkboxes are available in two sizes, regular and
dense
. Regular sized checkboxes are useful when there's space available. Usedense
sized checkboxes in compact, information-dense interfaces.
API Reference
Checkbox
Usage
To use Checkbox
, you can import the component from the @dhis2/ui
library
import { Checkbox } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
checked | custom | false | ||
className | string | |||
dataTest | string | 'dhis2-uicore-checkbox' | ||
dense | boolean | |||
disabled | boolean | |||
error | custom | |||
indeterminate | custom | false | ||
initialFocus | boolean | |||
label | node | |||
name | string | |||
tabIndex | string | |||
valid | custom | |||
value | string | |||
warning | custom | |||
onBlur | function | |||
onChange | function | Called with signature (object, event) | ||
onFocus | function | |||
onKeyDown | function |
CheckboxField
Usage
To use CheckboxField
, you can import the component from the @dhis2/ui
library
import { CheckboxField } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
checked | boolean | |||
className | string | |||
dataTest | string | 'dhis2-uiwidgets-checkboxfield' | ||
dense | boolean | Smaller dimensions for information-dense layouts | ||
disabled | boolean | Disables the checkbox | ||
error | custom | Applies 'error' styling to checkbox and validation text for feedback. Mutually exclusive with warning and valid props | ||
helpText | string | Useful instructions for the user | ||
initialFocus | boolean | |||
label | node | Labels the checkbox | ||
name | string | Name associate with the checkbox. Passed in object as argument to event handlers | ||
required | boolean | Adds an asterisk to indicate this field is required | ||
tabIndex | string | |||
valid | custom | Applies 'valid' styling to checkbox and validation text for feedback. Mutually exclusive with warning and error props | ||
validationText | string | Adds text below the checkbox to provide validation feedback. Acquires styles from valid , warning and error statuses | ||
value | string | Value associated with the checkbox. Passed in object as argument to event handlers | ||
warning | custom | Applies 'warning' styling to checkbox and validation text for feedback. Mutually exclusive with valid and error props | ||
onBlur | function | Called with signature ({ name: string, value: string, checked: bool }, event) | ||
onChange | function | Called with signature ({ name: string, value: string, checked: bool }, event) | ||
onFocus | function | Called with signature ({ name: string, value: string, checked: bool }, event) | ||
onKeyDown | function | Called with signature ({ name: string, value: string, checked: bool }, event) |