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. Usedense
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
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
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) |