(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Toggle switch

The Toggle Switch Component is a form control that provides a simple binary choice option presented as an on/off switch. This component is particularly useful for boolean settings, enabling/disabling features, or any scenario where users need to make a simple yes/no choice. The toggle switch offers better visual feedback than traditional checkboxes and takes up less space than radio buttons for binary selections.

Properties

Visual Properties

  • 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, which is useful for display-only scenarios or conditionally disabling options. For example, setting to "true" would prevent users from changing a system setting that shouldn't be modified under certain conditions.

  • value - Sets the initial state of the toggle switch (true = on, false = off). This boolean value determines whether the switch appears in the activated position when the form is first displayed. For example, setting to "true" would show the toggle switch in the on position by default.

  • 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. For example, setting to "true" would hide an optional setting that only applies in specific scenarios.

  • 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. For example, setting to "true" would remember a user's selected theme preference.

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

  • readonly - Controls whether the toggle state can be changed by users. When set to true, the toggle displays its state but cannot be modified, which is useful for displaying system statuses without allowing changes. For example, setting to "true" would show a feature's activation state without allowing modifications.

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. For example, setting to "enableNotifications" ensures the toggle state is submitted with this field name in the form data.

  • 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, which is standard for most form submissions, while "HEADER" would place the value in request headers.

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.

Event Actions

  • 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/hiding related fields.
    • ON_INIT_BASED_ON_USER_VIEW: Triggered specifically when the component initializes in user view mode rather than edit mode.

Testing Hooks

  • dataTestId - Sets the testing hook ID for automated testing. For example, setting to "notification-toggle" allows test scripts to reliably locate and interact with this specific toggle switch component.
  • No labels