The SelectionInput
widget provides a set of selectable items, such as
checkboxes, radio buttons, switches, or a dropdown menu. You can use this widget
to collect defined and standardized data from users. To collect undefined data
from users, use the TextInput
widget instead.
The SelectionInput
widget supports suggestions, which help users enter uniform
data, and on-change actions, which are
Actions
that run when a change
occurs in a selection input field, such as a user selecting or un-selecting an
item.
Chat apps can receive and process the value of selected items during form input events. For details about working with form inputs, see Receive form data.
Examples
This section provides examples of cards that use the SelectionInput
widget.
The examples use different types of section inputs:
Example 1: checkboxes
The following image displays a dialog that asks the user to specify whether a
contact is professional and/or personal with a SelectionInput
widget that
uses checkboxes:

SelectionInput
widget.
Here's the card's JSON:
JSON
{
"cardsV2": [
{
"cardId": "exampleCard",
"card": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"selectionInput": {
"type": "CHECK_BOX",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
]
}
]
}
}
]
}
Example 2: radio buttons
The following image displays a dialog that asks the user to specify whether a
contact is professional or personal with a SelectionInput
widget that uses
radio buttons:

SelectionInput
widget.
Here's the card's JSON:
JSON
{
"cardsV2": [
{
"cardId": "exampleCard",
"card": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"selectionInput": {
"type": "RADIO_BUTTON",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
]
}
]
}
}
]
}
Example 3: switches
The following image displays a dialog that asks the user to specify whether a
contact is professional or personal with a SelectionInput
widget that uses
switches:

SelectionInput
widget.
Here's the card's JSON:
Switches
{
"cardsV2": [
{
"cardId": "exampleCard",
"card": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"selectionInput": {
"type": "SWITCH",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
]
}
]
}
}
]
}
Example 4: dropdown menu
The following image displays a dialog that asks the user to specify whether a
contact is professional or personal with a SelectionInput
widget that uses
a dropdown menu:

SelectionInput
widget.
Here's the card's JSON:
Dropdown
{
"cardsV2": [
{
"cardId": "exampleCard",
"card": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"selectionInput": {
"type": "DROPDOWN",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
]
}
]
}
}
]
}
JSON representation and fields
JSON representation |
---|
{ "name": string, "label": string, "type": enum ( |
Fields | |
---|---|
name
|
The name that identifies the selection input in a form input event. For details about working with form inputs, see Receive form data. |
label
|
The text that appears above the selection input field in the user interface. Specify text that helps the user enter the information your app needs. For example, if users are selecting the urgency of a work ticket from a drop-down menu, the label might be "Urgency" or "Select urgency". |
type
|
The type of items that are displayed to users in a
|
items[]
|
An array of selectable items. For example, an array of radio buttons or checkboxes. Supports up to 100 items. |
onChangeAction
|
If specified, the form is submitted when the selection changes. If not specified, you must specify a separate button that submits the form. For details about working with form inputs, see Receive form data. |
SelectionType
Enums | |
---|---|
CHECK_BOX
|
A set of checkboxes. Users can select one or more checkboxes. |
RADIO_BUTTON
|
A set of radio buttons. Users can select one radio button. |
SWITCH
|
A set of switches. Users can turn on one or more switches. |
DROPDOWN
|
A dropdown menu. Users can select one item from the menu. |
SelectionItem
JSON representation |
---|
{ "text": string, "value": string, "selected": boolean } |
Fields | |
---|---|
text
|
The text that identifies or describes the item to users. |
value
|
The value associated with this item. The client should use this as a form input value. For details about working with form inputs, see Receive form data. |
selected
|
When
|
Action
An action that describes the behavior when the form is submitted. For example, you can invoke an Apps Script script to handle the form. If the action is triggered, the form values are sent to the server.
JSON representation |
---|
{ "function": string, "parameters": [ { object ( |
Fields | |
---|---|
function
|
A custom function to invoke when the containing element is clicked or othrwise activated. For example usage, see Create interactive cards. |
parameters[]
|
List of action parameters. |
loadIndicator
|
Specifies the loading indicator that the action displays while making the call to the action. |
persistValues
|
Indicates whether form values persist after the action. The default value is
If
If
|
interaction
|
Optional. Required when opening a dialog. What to do in response to an interaction with a user, such as a user clicking a button in a card message.
If unspecified, the app responds by executing an
By specifying an
Supported by Chat apps, but not Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client. |
ActionParameter
List of string parameters to supply when the action method is invoked. For example, consider three snooze buttons: snooze now, snooze one day, or snooze next week. You might use
action method = snooze()
, passing the snooze type and snooze time in the list of string parameters.
To learn more, see
CommonEventObject
.
JSON representation |
---|
{ "key": string, "value": string } |
Fields | |
---|---|
key
|
The name of the parameter for the action script. |
value
|
The value of the parameter. |
LoadIndicator
Specifies the loading indicator that the action displays while making the call to the action.
Enums | |
---|---|
SPINNER
|
Displays a spinner to indicate that content is loading. |
NONE
|
Nothing is displayed. |
Interaction
Optional. Required when opening a dialog.
What to do in response to an interaction with a user, such as a user clicking a button in a card message.
If unspecified, the app responds by executing an
action
—like opening a link or running a function—as normal.
By specifying an
interaction
, the app can respond in special interactive ways. For example, by setting
interaction
to
OPEN_DIALOG
, the app can open a
dialog.
When specified, a loading indicator isn't shown.
Supported by Chat apps, but not Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client.
Enums | |
---|---|
INTERACTION_UNSPECIFIED
|
Default value. The
action
executes as normal.
|
OPEN_DIALOG
|
Opens a dialog, a windowed, card-based interface that Chat apps use to interact with users. Only supported by Chat apps in response to button-clicks on card messages. Not supported by Google Workspace Add-ons. If specified for an add-on, the entire card is stripped and nothing is shown in the client. |