Switch
An EuiSwitch can be substituted for an EuiCheckbox when the semantics of the label dictate a true on/off state.
Make sure to pass a label
to ensure a larger clickable area and ensure that screen readers will read out the label when the user is focused on the input.
If the switch is described in some other manner, like when using an EuiFormRow, you can eliminate the visible label with showLabel={false}
or use it to further describe the state.
Accessibility requirement
When providing the state as the label, you'll need to provide an aria-describedby
with the label's id
to associate it with the switch.
Usage
Labels
The label should be static, action-oriented, and describe the feature. Avoid verbs that are less conversational such as "enable" unless they are your only option.
Do: Use a static noun describing the setting to turn on or off.
Don't: Start with statements such as "If true" or "If enabled".
Do: If relevant, start with a verb ("Use A", "Show B") and add help text to provide more info.
Don't: Use only a verb. Generic verbs alone make options unclear.
Use past tense only when labelling a list of previously created items, like in a table header.
Enabled | ||
---|---|---|
Do: In a list of already created items, use the past tense.
Don't: Change the label to represent the current state of the switch.
Props
EuiSwitch
Prop | Description and type | Default value |
---|---|---|
Prop label# | Description and type Must be a string if ReactNode | Default value Required |
Prop checked# | Description and type Type: boolean | Default value Required |
Prop onChange# | Description and type Type: (event: React.BaseSyntheticEvent<React.MouseEvent<HTMLButtonElement>, HTMLButtonElement, EventTarget & { checked: boolean; }>) => void | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop showLabel# | Description and type Whether to render the text label boolean | Default value true |
Prop disabled# | Description and type Type: boolean | Default value |
Prop compressed# | Description and type Compressed switches are smaller and contain no icon signifiers boolean | Default value |
Prop labelProps# | Description and type Object of props passed to the label's CommonProps & HTMLAttributes<HTMLSpanElement> | Default value |
Prop mini# | Description and type Mini styling is similar to compressed, but even smaller. boolean | Default value |