---
title: "Switch"
description: "Switches are used to toggle something between an on and off state."
url: https://developers.dhis2.org/docs/ui/components/switch
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/switch.md
---

# Switch

Switches are used to toggle something between an on and off state.

[Interactive demo: switch--focused-unchecked](https://developers.dhis2.org/demo/?path=/story/switch--focused-unchecked)

## Usage

```jsx
<Switch label="Switch" />
```

### When to use

- **Toggle a job or process**. Use a switch to toggle a constantly running process. Examples of constantly running processes might be _Automatic updates_, _Logging_, or a background task.

### When not to use

- **Toggling an option**. Don't use a switch to toggle options, like _Show legend set_. Options aren't constantly running processes. Use a [`Checkbox`](https://developers.dhis2.org/docs/ui/components/checkbox.md) instead.
- **Form controls**. Don't use a switch to toggle options in a form. Use a [`Checkbox`](https://developers.dhis2.org/docs/ui/components/checkbox.md) instead.

### Format

#### Label

- Always show a label next to a switch to make it clear what process will be toggled on and off.

#### Size

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

```jsx
<Switch checked dense label="Dense sized switch" />
```

- Switches are available in two sizes, regular and `dense`. Regular sized switches are useful when there's space available. Use `dense` sized switches in compact, information-dense interfaces.

## API Reference

### Switch

#### Usage

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

```js
import { Switch } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|aria-label|string|||Sets an aria-label attribute on the input|
|checked|boolean|``false``|||
|className|string||||
|dataTest|string|``'dhis2-uicore-switch'``|||
|dense|boolean|||Makes the switch smaller for information-dense layouts|
|disabled|boolean|||Disables the switch|
|error|custom|||Applies 'error' styles for validation feedback. Mutually exclusive with `valid` and `warning` prop types|
|initialFocus|boolean|||Grab initial focus on the page|
|label|node|||Label for the switch. Can be a string or an element, for example an image|
|name|string|||Name associated with the switch. Passed to event handlers in object|
|role|string|``'switch'``||Sets a role attribute on the input|
|tabIndex|string||||
|valid|custom|||Applies 'valid' styles for validation feedback. Mutually exclusive with `error` and `warning` prop types|
|value|string|||Value associated with the switch. Passed to event handlers in object|
|warning|custom|||Applies 'warning' styles for validation feedback. Mutually exclusive with `valid` and `error` prop types|
|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)`|

### SwitchField

#### Usage

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

```js
import { SwitchField } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|checked|boolean||||
|className|string||||
|dataTest|string|``'dhis2-uiwidgets-switchfield'``|||
|dense|boolean|||Smaller dimensions for information-dense layouts|
|disabled|boolean|||Disables the switch|
|error|custom|||Applies 'error' styling to switch 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 switch|
|name|string|||Name associate with the switch. 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 switch and validation text for feedback. Mutually exclusive with `warning` and `error` props|
|validationText|string|||Adds text below the switch to provide validation feedback. Acquires styles from `valid`, `warning` and `error` statuses|
|value|string|||Value associated with the switch. Passed in object as argument to event handlers|
|warning|custom|||Applies 'warning' styling to switch 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)`|
