TextInput

Stay organized with collections Save and categorize content based on your preferences.

Only supported in dialogs. Support for card messages coming soon.

The TextInput widget provides a field in which users can enter text. The widget supports suggestions, which help users enter uniform data, and on-change actions, which are Actions that run when a change occurs in the text input field, like a user adding or deleting text.

When you need to collect abstract or unknown data from users, use this TextInput widget. To collect defined data from users, use the SelectionInput widget instead.

Chat apps receive and can process the value of entered text during form input events. For details about working with form inputs, see Receive form data.

Example

The following image displays a card consisting of a TextInput widget.

A dialog featuring a variety of different widgets.
Figure 1: A dialog helping a user create a new contact for their address book. The name and address fields are TextInput widgets.

Here's the card's JSON:

JSON

{
  "cardsV2": [
    {
      "cardId": "exampleCard",
      "card": {
        "sections": [
          {
            "header": "Add new contact",
            "widgets": [
              {
                "textInput": {
                  "label": "Name",
                  "type": "SINGLE_LINE",
                  "name": "contactName"
                }
              },
              {
                "textInput": {
                  "label": "Address",
                  "type": "MULTIPLE_LINE",
                  "name": "address"
                }
              },
              {
                "decoratedText": {
                  "text": "Add to favorites",
                  "switchControl": {
                    "controlType": "SWITCH",
                    "name": "saveFavorite"
                  }
                }
              },
              {
                "decoratedText": {
                  "text": "Merge with existing contacts",
                  "switchControl": {
                    "controlType": "SWITCH",
                    "name": "mergeContact",
                    "selected": true
                  }
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Next",
                      "onClick": {
                        "action": {
                          "function": "openSequentialDialog"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

TextInput JSON representation and fields

JSON representation
{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  }
}
Fields
name

string

The name by which the text input is identified in a form input event.

For details about working with form inputs, see Receive form data .

label

string

The text that appears above the text input field in the user interface.

Specify text that helps the user enter the information your app needs. For example, if you are asking someone's name, but specifically need their surname, write "surname" instead of "name".

Required if hintText is unspecified. Otherwise, optional.

hintText

string

Text that appears below the text input field meant to assist users by prompting them to enter a certain value. This text is always visible.

Required if label is unspecified. Otherwise, optional.

value

string

The value entered by a user, returned as part of a form input event.

For details about working with form inputs, see Receive form data .

type

enum ( Type )

How a text input field appears in the user interface. For example, whether the field is single or multi-line.

onChangeAction

object ( Action )

What to do when a change occurs in the text input field.

Examples of changes include a user adding to the field, or deleting text.

Examples of actions to take include running a custom function or opening a dialog in Google Chat.

initialSuggestions

object ( Suggestions )

Suggested values that users can enter. These values appear when users click inside the text input field. As users type, the suggested values dynamically filter to match what the users have typed.

For example, a text input field for programming language might suggest Java, JavaScript, Python, and C++. When users start typing "Jav", the list of suggestions filters to show just Java and JavaScript.

Suggested values help guide users to enter values that your app can make sense of. When referring to JavaScript, some users might enter "javascript" and others "java script". Suggesting "JavaScript" can standardize how users interact with your app.

When specified, TextInput.type is always SINGLE_LINE , even if it is set to MULTIPLE_LINE .

autoCompleteAction

object ( Action )

Optional. Specify what action to take when the text input field provides suggestions to users who interact with it.

If unspecified, the suggestions are set by initialSuggestions and are processed by the client.

If specified, the app takes the action specified here, such as running a custom function.

Supported by Google Workspace Add-ons, but not Chat apps. Support by Chat apps coming soon.

Suggestions JSON representation and fields

JSON representation
{
  "items": [
    {
      object (SuggestionItem)
    }
  ]
}
Fields
items[]

object ( SuggestionItem )

A list of suggestions used for autocomplete recommendations in text input fields.

SuggestionItem JSON representation and fields

JSON representation
{

  // Union field content can be only one of the following:
  "text": string
  // End of list of possible types for union field content.
}
Fields

Union field content .

content can be only one of the following:

text

string

The value of a suggested input to a text input field. This is equivalent to what users would enter themselves.