Skip to main content

Switch Group (ALPHA)

Alpha feature: invite only

Responsive Widgets are in alpha and available by invitation only on Business and Enterprise plans. Behavior and properties may change. To request access, open a support ticket and name the feature Responsive Widgets (ALPHA).

The Switch Group widget shows a list of switches under one label. Users can turn any number of them on. Use it for a set of related settings, for example which email alerts to receive.

Switch Group widget in a Responsive app
Switch Group widget

Widget type: WDS_SWITCH_GROUP_WIDGET

Content properties​

These properties appear in the Content tab of the property pane.

Data​

Options array<object>​

Sets the switches. Each option has a label and a value. Labels and values must be unique. You can add options in the property pane or switch to JS to bind an array.

Default value:

[
{ "label": "Blue", "value": "BLUE" },
{ "label": "Green", "value": "GREEN" },
{ "label": "Red", "value": "RED" }
]

Default selected values array<string>​

Sets the options that are on when the widget loads. Enter an array of strings. Default: ["BLUE", "RED"].

Example:

["GREEN"]

Orientation string​

Sets how the switches are laid out. Options:

  • Horizontal: in a row.
  • Vertical: in a column.

Default: Vertical.

Options Label Position string​

Sets where each option's label appears. You cannot bind this property. Options:

  • Start: the label appears before the switch.
  • End: the label appears after the switch.

Default: End.

Label​

Text string​

Sets the label shown above the group. Default: Label.

Tooltip string​

Shows help text or details next to the label.

Validations​

Required boolean​

Makes turning on at least one option mandatory. When on and no option is on, the widget is invalid and shows the message "Please select an option" after the user interacts with it. Default: off.

General​

Visible boolean​

Controls whether the widget is visible when the app runs. Default: on.

Disabled boolean​

Stops users from changing the switches. Default: off.

Animate loading boolean​

Shows a loading animation while the widget's data loads. Default: on.

Style properties​

These properties appear in the Style tab of the property pane.

Custom styling​

These settings are in the Custom styling section, at the end of the Style tab. An empty setting uses the theme value. For theme colors, dark mode, and the rules for custom CSS, see Custom styling.

Accent color string​

Builds the hover, pressed, focus, and text colors of this widget from one color, in light and dark mode. Lists and menus that the widget opens use them too. Empty means the accent of the nearest container that sets one, or the theme accent.

Custom CSS string​

Adds plain CSS to this widget. Rules apply only inside the widget, and & is the box around the widget, its label included, not the part inside it. To style an inner part, use its element selector, for example button or input. You cannot bind this property.

Reference properties​

Reference properties let you read the widget's state in bindings and code, for example {{SwitchGroup1.isVisible}}. You cannot set them directly.

isVisible boolean​

Shows whether the widget is visible.

Example:

{{SwitchGroup1.isVisible}}

isDisabled boolean​

Shows whether the widget is disabled.

Example:

{{SwitchGroup1.isDisabled}}

isRequired boolean​

Shows whether Required is on.

Example:

{{SwitchGroup1.isRequired}}

isValid boolean​

Shows whether the widget is valid. It is false only when Required is on and no option is on.

Example:

{{SwitchGroup1.isValid}}

options array<object>​

Holds the options set in Options.

Example:

{{SwitchGroup1.options}}

selectedValues array<string>​

Holds the values of the options that are on.

Example:

{{SwitchGroup1.selectedValues}}

Methods​

Methods let you change the widget's properties from code, for example in a JS Object.

setVisibility (param: boolean): Promise​

Shows or hides the widget.

Example:

SwitchGroup1.setVisibility(true)

setDisabled (param: boolean): Promise​

Turns the disabled state on or off.

Example:

SwitchGroup1.setDisabled(false)

setSelectedOptions (param: array): Promise​

Sets which options are on, by their values.

Example:

SwitchGroup1.setSelectedOptions(["GREEN", "RED"])

Events​

onSelectionChange​

Runs when the user turns an option on or off.