Skip to main content

Switch

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

Demo

Usage

<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 instead.
  • Form controls. Don't use a switch to toggle options in a form. Use a Checkbox instead.

Format

Label

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

Size

Demo
<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

import { Switch } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
aria-labelstringSets an aria-label attribute on the input
checkedbooleanfalse
classNamestring
dataTeststring'dhis2-uicore-switch'
densebooleanMakes the switch smaller for information-dense layouts
disabledbooleanDisables the switch
errorcustomApplies 'error' styles for validation feedback. Mutually exclusive with valid and warning prop types
initialFocusbooleanGrab initial focus on the page
labelnodeLabel for the switch. Can be a string or an element, for example an image
namestringName associated with the switch. Passed to event handlers in object
rolestring'switch'Sets a role attribute on the input
tabIndexstring
validcustomApplies 'valid' styles for validation feedback. Mutually exclusive with error and warning prop types
valuestringValue associated with the switch. Passed to event handlers in object
warningcustomApplies 'warning' styles for validation feedback. Mutually exclusive with valid and error prop types
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)

SwitchField

Usage

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

import { SwitchField } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
checkedboolean
classNamestring
dataTeststring'dhis2-uiwidgets-switchfield'
densebooleanSmaller dimensions for information-dense layouts
disabledbooleanDisables the switch
errorcustomApplies 'error' styling to switch and validation text for feedback. Mutually exclusive with warning and valid props
helpTextstringUseful instructions for the user
initialFocusboolean
labelnodeLabels the switch
namestringName associate with the switch. Passed in object as argument to event handlers
requiredbooleanAdds an asterisk to indicate this field is required
tabIndexstring
validcustomApplies 'valid' styling to switch and validation text for feedback. Mutually exclusive with warning and error props
validationTextstringAdds text below the switch to provide validation feedback. Acquires styles from valid, warning and error statuses
valuestringValue associated with the switch. Passed in object as argument to event handlers
warningcustomApplies 'warning' styling to switch 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)