(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)
Toggle Switch
Overview
- The Toggle Switch Component is a form control that offers a simple on/off choice.
- It is used for boolean settings such as enabling or disabling features.
- The switch provides clear visual feedback compared to checkboxes.
- It saves space compared to radio buttons for binary options.
Specs
Tokens
| Token |
Description |
| disabled |
Disables user interaction. |
| value |
Initial on/off state. |
| hidden |
Keeps in form but not visible. |
| saveInLocalStorage |
Persists state between sessions. |
| defaultValue |
Reset value for form reset. |
| readonly |
Shows state but cannot change. |
| dataField |
Field name used on submit. |
| controlsRequestType |
Where value is sent: BODY, HEADER, or PATH. |
| authorizationDisable |
Policy set that disables by permissions. |
| events |
Configures component events. |
| ON_INIT (Events) |
Runs on component initialization. |
| ON_DESTROY (Events) |
Runs when component is removed. |
| ON_VALUE_CHANGE (Events) |
Runs when user toggles value. |
| ON_INIT_BASED_ON_USER_VIEW (Events) |
Runs on init in user view mode. |
| dataTestId |
Testing hook ID. |
Structure
(Configured in Non-Visual Properties)
- dataField – Defines the field name that will be used when submitting form data. This establishes how the toggle's boolean value will be identified in the data object.
- controlsRequestType – Specifies how the field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the toggle's value in the request body, while "HEADER" would place the value in request headers.
(Configured in Visual Properties)
- saveInLocalStorage – Determines whether the toggle's state is preserved in the user's local storage between sessions. When enabled, the last selected value will persist if the user reloads the page, providing a better user experience for preference settings.
- defaultValue – Sets the initial value that will be used when the form is reset. This provides a starting point that can be different from the current value. For example, setting to "false" ensures the toggle resets to the off position when a form reset action is triggered.
Actions & Variants
(Configured in Events)
- events – Configures the events that the component can trigger and respond to.
- ON_INIT – Triggered when the toggle switch component is initialized. Can be used to perform setup operations or initial state calculations.
- ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.
- ON_VALUE_CHANGE – Triggered when the user toggles the switch. Can be used to perform immediate actions based on the new state, such as showing or hiding related fields.
- ON_INIT_BASED_ON_USER_VIEW – Triggered specifically when the component initializes in user view mode rather than edit mode.
(Configured in Visual Properties)
- hidden – Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional rendering based on other field values.
- disabled – Controls whether users can interact with the toggle switch. When set to true, the toggle appears grayed out and cannot be changed by users.
- readonly – Controls whether the toggle state can be changed by users. When set to true, the toggle displays its state but cannot be modified.
Tests
(Configured in Testing Hooks)
- dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "notification-toggle" allows test scripts to reliably locate and interact with this specific toggle switch component.
Authorization
(Configured in Authorization Properties)
- authorizationDisable – Specifies a policy set that determines when the component should be disabled based on user permissions. For example, setting to "adminOnlyEditPolicy" will disable the toggle for non-admin users while allowing admins to change its state.
Guidelines
- Always design the toggle for fast and intuitive input with minimal clicks.
- Ensure high contrast between on/off states so users with low vision or in noisy/low-light environments can distinguish states.
- Do not rely on color alone to indicate state; include position and clear visual feedback.
- Support color-blind users by ensuring on/off states are distinguishable without red/green dependency.
- Maintain consistency across themes (Daylight/Nightshift) so toggles remain recognizable.
Accessibility
- Ensure the toggle switch is keyboard accessible (can be focused and toggled using standard keys such as Tab and Space/Enter).
- Provide clear labels that describe what the toggle controls; avoid relying only on its visual state.
- Use ARIA roles and states (e.g., role="switch", aria-checked="true/false"`) to make the toggle state available to screen readers.
- Guarantee sufficient color contrast between on/off states to meet WCAG standards.
- Avoid using only color cues; include position change or iconography to reinforce state.