(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.

Example Switch

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.

Different versions

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.
  • Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11600-78630&t=ftfrOGkPzlG2GaTo-1
  • Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/4-toggle

Guidelines

Usage

  • Always design the toggle for fast and intuitive input with minimal clicks.
  • Use for binary, immediate preferences or feature flags; set intent with value and a distinct reset via defaultValue.
  • Persist preference-style choices across sessions by enabling saveInLocalStorage.
  • Remove from view when not applicable using hidden (remains part of the form data if needed).
  • Communicate permission limits without removing context by disabling via authorizationDisable; optionally present as readonly when edits aren’t allowed.

Sizing & Layout

  • Keep the surface tidy by conditionally removing the control with hidden rather than leaving inert space.
  • Make form resets predictable by setting defaultValue separately from the current value.

States & Feedback

  • Express non-interactive states with disabled or readonly (shows state, prevents changes).
  • Reflect the current on/off state with value; run dependent logic on change via ON_VALUE_CHANGE.
  • Persist user changes for preferences with saveInLocalStorage.

Visibility & Authorization

  • Hide when the setting must not be shown or is irrelevant (hidden: true).
  • Disable when discoverability matters but edits are blocked (authorizationDisable with disabled or readonly).

Dos & Don’ts

Do Don’t
Set a safe initial value and a distinct defaultValue for resets. Reuse one value for both current and reset, causing unexpected form state after reset.
Enable saveInLocalStorage for persistent preferences. Force users to reconfigure the same preference every session.
Use hidden to remove irrelevant controls from view and reading order. Leave a visible but meaningless control on screen.
Prefer authorizationDisable + disabled/readonly to show blocked settings. Hide controls that users should be aware exist but cannot change.
Submit with a clear dataField and correct controlsRequestType. Send the boolean in the wrong channel (e.g., header instead of body).
Handle changes immediately with ON_VALUE_CHANGE. Defer processing until an unrelated action.
Clean up listeners/timers with ON_DESTROY. Leave background work running after navigation.

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.
  • No labels