Switch

The switch element is a toggle with two states: on and off. The state is stored in a boolean variable, so you can use it in expressions and change it with actions. The look of the toggle is defined by the platform, and the layout only sets the color of the on state.

Switch element properties

  • is_on_variable: string, required. The name of the boolean variable that stores the toggle state. Expressions aren't supported in this parameter.
  • is_enabled: bool, default value: true. Determines whether the user can toggle the element. With the false value, the toggle doesn't respond to taps and looks inactive.
  • on_color: color. The color of the toggle in the on state in the #RGB, #ARGB, #RRGGBB, or #AARRGGBB format. If the parameter isn't set, the default color is used, which depends on the platform.

The is_enabled and on_color parameters support expressions. The remaining properties, such as sizes, margins, and visibility, are the same as for other elements. For a detailed description of the switch element properties, see the element reference book.

Binding to a variable

Declare a boolean variable and specify its name in the is_on_variable parameter. The toggle and the variable are bound both ways:

  • When the user taps the toggle, the new value is written to the variable: true for the on state and false for the off state.
  • When the variable value changes, for example after a set_variable action, the toggle moves to the matching position. This happens even if the toggle is disabled with the is_enabled parameter.

The switch element has no tap actions (actions). To react to toggling, use triggers on the variable from is_on_variable or use this variable in expressions in the properties of other elements.

In the following example, two toggles control the notifications_enabled and sound_enabled variables. The second toggle is available only while the first one is on, and a trigger turns the sound off when the user disables notifications.

Sample code
{
  "card": {
    "log_id": "switch_sample",
    "variables": [
      {
        "name": "notifications_enabled",
        "type": "boolean",
        "value": true
      },
      {
        "name": "sound_enabled",
        "type": "boolean",
        "value": false
      }
    ],
    "variable_triggers": [
      {
        "condition": "@{!notifications_enabled}",
        "mode": "on_condition",
        "actions": [
          {
            "log_id": "turn_sound_off",
            "url": "div-action://set_variable?name=sound_enabled&value=false"
          }
        ]
      }
    ],
    "states": [
      {
        "state_id": 0,
        "div": {
          "type": "container",
          "orientation": "vertical",
          "paddings": {
            "left": 16,
            "top": 12,
            "right": 16,
            "bottom": 12
          },
          "items": [
            {
              "type": "container",
              "orientation": "horizontal",
              "content_alignment_vertical": "center",
              "items": [
                {
                  "type": "text",
                  "text": "Notifications",
                  "font_size": 16
                },
                {
                  "type": "switch",
                  "id": "notifications_switch",
                  "is_on_variable": "notifications_enabled",
                  "on_color": "#0077FF",
                  "width": {
                    "type": "wrap_content"
                  },
                  "accessibility": {
                    "description": "Notifications"
                  }
                }
              ]
            },
            {
              "type": "container",
              "orientation": "horizontal",
              "content_alignment_vertical": "center",
              "margins": {
                "top": 12
              },
              "items": [
                {
                  "type": "text",
                  "text": "Sound",
                  "font_size": 16
                },
                {
                  "type": "switch",
                  "id": "sound_switch",
                  "is_on_variable": "sound_enabled",
                  "is_enabled": "@{notifications_enabled}",
                  "on_color": "#0077FF",
                  "width": {
                    "type": "wrap_content"
                  },
                  "accessibility": {
                    "description": "Sound"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Size and position

The toggle doesn't stretch: it keeps its native size on each platform. The width and height parameters set the size of the element area, and the toggle itself is placed in its center.

The default element width is match_parent. To put the toggle on the same line as the text, as in the example above, set its width to wrap_content.

Platform specifics

The default color, which is used if the on_color parameter isn't set:

  • iOS: The standard system color.
  • Android: The color from the colorControlActivated theme attribute.
  • Web: #129386.

How the on_color parameter is applied:

  • iOS: The track of the toggle in the on state is painted in this color.
  • Android and Web: The thumb is painted in this color, and the track gets the same color with additional transparency.

Restrictions on the Web platform:

  • The toggle isn't rendered if it is nested in an element that has actions, or if the exclude accessibility mode is set for the toggle or for a parent element. In this case, the onError handler receives an error.
  • If the accessibility.description description isn't set for the toggle, the onError handler receives a warning. The description is used as the toggle label for assistive technologies.

Learn more

You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.

DivKit Repository

Previous
Slider
Next
Accessibility