Skip to main content

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. Use dense 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

NameTypeDefaultRequiredDescription
checkedcustomfalse
classNamestring
dataTeststring'dhis2-uicore-checkbox'
denseboolean
disabledboolean
errorcustom
indeterminatecustomfalse
initialFocusboolean
labelnode
namestring
tabIndexstring
validcustom
valuestring
warningcustom
onBlurfunction
onChangefunctionCalled with signature (object, event)
onFocusfunction
onKeyDownfunction

CheckboxField

Usage

To use CheckboxField, you can import the component from the @dhis2/ui library

import { CheckboxField } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
checkedboolean
classNamestring
dataTeststring'dhis2-uiwidgets-checkboxfield'
densebooleanSmaller dimensions for information-dense layouts
disabledbooleanDisables the checkbox
errorcustomApplies 'error' styling to checkbox and validation text for feedback. Mutually exclusive with warning and valid props
helpTextstringUseful instructions for the user
initialFocusboolean
labelnodeLabels the checkbox
namestringName associate with the checkbox. Passed in object as argument to event handlers
requiredbooleanAdds an asterisk to indicate this field is required
tabIndexstring
validcustomApplies 'valid' styling to checkbox and validation text for feedback. Mutually exclusive with warning and error props
validationTextstringAdds text below the checkbox to provide validation feedback. Acquires styles from valid, warning and error statuses
valuestringValue associated with the checkbox. Passed in object as argument to event handlers
warningcustomApplies 'warning' styling to checkbox and validation text for feedback. Mutually exclusive with valid and error props
onBlurfunctionCalled with signature ({ name: string, value: string, checked: bool }, event)
onChangefunctionCalled with signature ({ name: string, value: string, checked: bool }, event)
onFocusfunctionCalled with signature ({ name: string, value: string, checked: bool }, event)
onKeyDownfunctionCalled with signature ({ name: string, value: string, checked: bool }, event)