Switch provides "on" and "off" choices and can be useful for opt-in and additive actions.
Overview
Switches should be used for boolean and "on" and "off" choices. They should not be for binary choices such as "1 or 2", "blue or red", "sky or ground", "miles or kilometers", "large or small", etc.
For "yes" and "no" interactions, multiple selections, and interactions where a choice is optional, please consider Checkbox.
For single choice interactions, please consider Radio Button or Segmented Control.
Usage
- Dark mode switch
- Layer visibility
Sample
<calcite-switch></calcite-switch>
Best practices
Below are important guidelines on using the Switch component.
Accessibility
Switch should include a label
property value, or be accompanied by a Label, which provides context of the intent to support assistive technologies.
Keyboard navigation
Key | Function |
---|---|
Tab | Moves focus in or out of component. |
Tab and Shift | Move focus in or out of component. |
Enter | Toggles the component. |
Space | Toggles the component. |
Writing and copy
Keep labels for Switches succinct. Do not use contractions such as "you're", "aren't", "can't", and "haven't" for Switch labels in order to reduce confusion. Avoid writing Switch text as a question.
A label for a Switch should be supporting "On" as additive, not subtractive. For example:
- Show layer
- Enable editing
- Allow credit usage
- Display controls
- Update automatically
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
checked | checked | When true , the component is checked. | boolean | false |
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
form | form | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | string | |
label | label | Accessible name for the component. | string | |
name | name | Specifies the name of the component.
Required to pass the component's value on form submission. | string | |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
value | value | The component's value. | any |
Styles
Name | Description |
---|---|
--calcite-switch-background-color | Specifies the component's background color. |
--calcite-switch-border-color | Specifies the component's border color. |
--calcite-switch-corner-radius | Specifies the component's corner radius. |
--calcite-switch-handle-background-color | Specifies the handle's background color. |
--calcite-switch-handle-border-color | Specifies the handle's border color. |
--calcite-switch-handle-shadow | Specifies the handle's shadow. |
Events
Name | Description | Behavior |
---|---|---|
calciteSwitchChange | Fires when the checked value has changed. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |