---
title: "Checkbox"
description: "Checkboxes are used to choose one or more items from a list. A checkbox can also be used to toggle an option."
url: https://developers.dhis2.org/docs/ui/components/checkbox
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/checkbox.md
---

# Checkbox

Checkboxes are used to choose one or more items from a list. A checkbox can also be used to toggle an option.

[Interactive demo: checkbox--checked](https://developers.dhis2.org/demo/?path=/story/checkbox--checked)

```jsx
<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`](https://developers.dhis2.org/docs/ui/components/radio.md) 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`](https://developers.dhis2.org/docs/ui/components/select.md) 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

[Interactive demo: checkbox--checked-dense](https://developers.dhis2.org/demo/?path=/story/checkbox--checked-dense)

```jsx
<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  

```js
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  

```js
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)`|
