Switch

A UI element that supports being toggled on or off. This can only be used within a `https://developers.google.com/apps-script/reference/card-service/decorated-text` widget.

Available for Google Workspace add-ons and Google Chat apps.

```javascript
const switchDecoratedText =
    CardService.newDecoratedText()
        .setTopLabel('Switch decorated text widget label')
        .setText('This is a decorated text widget with a switch on the right')
        .setWrapText(true)
        .setSwitchControl(
            CardService.newSwitch()
                .setFieldName('form_input_switch_key')
                .setValue('form_input_switch_value')
                .setOnChangeAction(
                    CardService.newAction().setFunctionName(
                        'handleSwitchChange'),
                    ),
        );
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/switch#setControlType(SwitchControlType)` | `https://developers.google.com/apps-script/reference/card-service/switch#` | Sets the control type of the switch. |
| `https://developers.google.com/apps-script/reference/card-service/switch#setFieldName(String)` | `https://developers.google.com/apps-script/reference/card-service/switch#` | Sets the key that identifies this switch in the event object that is generated when there is a UI interaction. |
| `https://developers.google.com/apps-script/reference/card-service/switch#setOnChangeAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/switch#` | Sets the action to take when the switch is toggled. |
| `https://developers.google.com/apps-script/reference/card-service/switch#setSelected(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/switch#` | Sets whether this switch should start as selected or unselected. |
| `https://developers.google.com/apps-script/reference/card-service/switch#setValue(String)` | `https://developers.google.com/apps-script/reference/card-service/switch#` | Sets the value that is sent as the form input when this switch is toggled on. |

## Detailed documentation

### `setControlType(controlType)`

Sets the control type of the switch. Defaults to `SWITCH`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `controlType` | `https://developers.google.com/apps-script/reference/card-service/switch-control-type` | The switch control type. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/switch#` --- This object, for chaining.

*** ** * ** ***

### `setFieldName(fieldName)`

Sets the key that identifies this switch in the event object that is generated when there is a
UI interaction. Not visible to the user. Required.

Unlike other form fields, this field name does not need to be unique. The form input values
for switches using the same field name are returned as an array. The array consists of the
values for all enabled switches with that field name.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `fieldName` | `String` | The key that is used to identify this switch. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/switch#` --- This object, for chaining.

*** ** * ** ***

### `setOnChangeAction(action)`

Sets the action to take when the switch is toggled.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The action to take when the switch is toggled. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/switch#` --- This object, for chaining.

*** ** * ** ***

### `setSelected(selected)`

Sets whether this switch should start as selected or unselected.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `selected` | `Boolean` | The starting switch state setting. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/switch#` --- This object, for chaining.

*** ** * ** ***

### `setValue(value)`

Sets the value that is sent as the form input when this switch is toggled on.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The value associated with the name when the switch is on. When this is sent to the form callback, it is always represented as a string. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/switch#` --- This object, for chaining.