CardSection

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

CardSection is a high-level container within a card. You use card sections to group widgets within a card. For each card section, you can include a header and one or more widgets.

You can include sections for card messages and dialogs.

Example

The following image displays a card consisting of a CardSection component.

A card message in Google Chat depicting a collapsible CardSection.
Figure 1: A card message in Google Chat depicting CardSection displaying a header and two TextParagraph widgets. The second text paragraph is collapsed.

Here's the card's JSON:

JSON

{
  "cardsV2": [
    {
      "cardId": "card_one",
      "card": {
        "sections": [
          {
          "header": "List of Collapsible Text Paragraphs",
          "collapsible": true,
          "uncollapsibleWidgetsCount": 1,
          "widgets": [
            {
              "textParagraph": {
                "text": "This is a normal test string 1",
              }
            },
            {
              "textParagraph": {
                "text": "This is a normal test string 2",
              }
            }
          ]
        }]
      }
    }
  ]
}

Section JSON representation and fields

A section contains a collection of widgets that are rendered vertically in the order that they are specified.

JSON representation
{
  "header": string,
  "widgets": [
    {
      object (Widget)
    }
  ],
  "collapsible": boolean,
  "uncollapsibleWidgetsCount": integer
}
Fields
header

string

Text that appears at the top of a section. Supports simple HTML formatted text .

widgets[]

object ( Widget )

All the widgets in the section. Must contain at least 1 widget.

collapsible

boolean

Indicates whether this section is collapsible.

Collapsible sections hide some or all widgets, but users can expand the section to reveal the hidden widgets by clicking Show more . Users can hide the widgets again by clicking Show less .

To determine which widgets are hidden, specify uncollapsibleWidgetsCount .

uncollapsibleWidgetsCount

integer

The number of uncollapsible widgets which remain visible even when a section is collapsed.

For example, when a section contains five widgets and the uncollapsibleWidgetsCount is set to 2 , the first two widgets are always shown and the last three are collapsed by default. The uncollapsibleWidgetsCount is taken into account only when collapsible is true .

Widget

Each card is made up of widgets.

A widget is a composite object that can represent one of text, images, buttons, and other object types.

JSON representation
{

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "image": {
    object (Image)
  },
  "decoratedText": {
    object (DecoratedText)
  },
  "buttonList": {
    object (ButtonList)
  },
  "textInput": {
    object (TextInput)
  },
  "selectionInput": {
    object (SelectionInput)
  },
  "dateTimePicker": {
    object (DateTimePicker)
  },
  "divider": {
    object (Divider)
  },
  "grid": {
    object (Grid)
  }
  // End of list of possible types for union field data.
}
Fields
Union field data . A widget can only have one of the following items. You can use multiple widget fields to display more items. data can be only one of the following:
textParagraph

object ( TextParagraph )

Displays a text paragraph. Supports simple HTML formatted text .

For example, the following JSON creates a bolded text:

"textParagraph": {
  "text": "  <b>bold text</b>"
}
image

object ( Image )

Displays an image.

For example, the following JSON creates an image with alternative text:

"image": {
  "imageUrl":
  "https://developers.google.com/chat/images/quickstart-app-avatar.png",
  "altText": "Chat app avatar"
}
decoratedText

object ( DecoratedText )

Displays a decorated text item.

For example, the following JSON creates a decorated text widget showing email address:

"decoratedText": {
  "icon": {
    "knownIcon": "EMAIL"
  },
  "topLabel": "Email Address",
  "text": "sasha@example.com",
  "bottomLabel": "This is a new Email address!",
  "switchControl": {
    "name": "has_send_welcome_email_to_sasha",
    "selected": false,
    "controlType": "CHECKBOX"
  }
}
buttonList

object ( ButtonList )

A list of buttons.

For example, the following JSON creates two buttons. The first is a blue text button and the second is an image button that opens a link:

"buttonList": {
  "buttons": [
    {
      "text": "Edit",
      "color": {
        "red": 0,
        "green": 0,
        "blue": 1,
        "alpha": 1
      },
      "disabled": true,
    },
    {
      "icon": {
        "knownIcon": "INVITE",
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    }
  ]
}
textInput

object ( TextInput )

Displays a text box that users can type into.

For example, the following JSON creates a text input for an email address:

"textInput": {
  "name": "mailing_address",
  "label": "Mailing Address"
}

As another example, the following JSON creates a text input for a programming language with static suggestions:

"textInput": {
  "name": "preferred_programing_language",
  "label": "Preferred Language",
  "initialSuggestions": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
selectionInput

object ( SelectionInput )

Displays a selection control that lets users select items. Selection controls can be check boxes, radio buttons, switches, or dropdown menus.

For example, the following JSON creates a dropdown menu that lets users choose a size:

"selectionInput": {
  "name": "size",
  "label": "Size"
  "type": "DROPDOWN",
  "items": [
    {
      "text": "S",
      "value": "small",
      "selected": false
    },
    {
      "text": "M",
      "value": "medium",
      "selected": true
    },
    {
      "text": "L",
      "value": "large",
      "selected": false
    },
    {
      "text": "XL",
      "value": "extra_large",
      "selected": false
    }
  ]
}
dateTimePicker

object ( DateTimePicker )

Displays a selection/input widget for date, time, or date and time.

Not supported by Chat apps. Support by Chat apps is coming soon.

For example, the following JSON creates a datetime picker to schedule an appointment:

"dateTimePicker": {
  "name": "appointment_time",
  "label": "Book your appointment at:",
  "type": "DATE_AND_TIME",
  "valueMsEpoch": "796435200000"
}
divider

object ( Divider )

Displays a horizontal line divider between widgets.

For example, the following JSON creates a divider:

"divider": {
}
grid

object ( Grid )

Displays a grid with a collection of items.

A grid supports any number of columns and items. The number of rows is determined by the upper bounds of the number items divided by the number of columns. A grid with 10 items and 2 columns has 5 rows. A grid with 11 items and 2 columns has 6 rows.

For example, the following JSON creates a 2 column grid with a single item:

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}

TextParagraph

A paragraph of text that supports formatting. See Text formatting for details.

JSON representation
{
  "text": string
}
Fields
text

string

The text that's shown in the widget.

Image

An image that is specified by a URL and can have an onClick action.

JSON representation
{
  "imageUrl": string,
  "onClick": {
    object (OnClick)
  },
  "altText": string
}
Fields
imageUrl

string

The https URL that hosts the image.

For example:

https://developers.google.com/chat/images/quickstart-app-avatar.png
onClick

object ( OnClick )

When a user clicks on the image, the click triggers this action.

altText

string

The alternative text of this image, used for accessibility.

DecoratedText

A widget that displays text with optional decorations such as a label above or below the text, an icon in front of the text, a selection widget or a button after the text.

JSON representation
{
  "icon": {
    object (Icon)
  },
  "startIcon": {
    object (Icon)
  },
  "topLabel": string,
  "text": string,
  "wrapText": boolean,
  "bottomLabel": string,
  "onClick": {
    object (OnClick)
  },

  // Union field control can be only one of the following:
  "button": {
    object (Button)
  },
  "switchControl": {
    object (SwitchControl)
  },
  "endIcon": {
    object (Icon)
  }
  // End of list of possible types for union field control.
}
Fields
icon
(deprecated)

object ( Icon )

Deprecated in favor of startIcon .

startIcon

object ( Icon )

The icon displayed in front of the text.

topLabel

string

The text that appears above text . Always truncates.

text

string

Required. The primary text.

Supports simple formatting. See Text formatting for formatting details.

wrapText

boolean

The wrap text setting. If true , the text wraps and displays on multiple lines. Otherwise, the text is truncated.

Only applies to text , not topLabel and bottomLabel .

bottomLabel

string

The text that appears below text . Always truncates.

onClick

object ( OnClick )

When users click on topLabel or bottomLabel , this action triggers.

Union field control . A button, switch, checkbox, or image that appears to the right-hand side of text in the decoratedText widget. control can be only one of the following:
button

object ( Button )

A button that can be clicked to trigger an action.

switchControl

object ( SwitchControl )

A switch widget can be clicked to change its state and trigger an action.

endIcon

object ( Icon )

An icon displayed after the text.

Supports built-in and custom icons.

ButtonList

A list of buttons layed out horizontally.

JSON representation
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
Fields
buttons[]

object ( Button )

An array of buttons.

TextInput

A field in which users can enter text. Supports suggestions and on-change actions.

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 .

When you need to collect abstract data from users, use a text input. To collect defined data from users, use the selection input widget instead.

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.

SelectionInput

A widget that creates a UI item with options for users to select. For example, a dropdown menu or check list.

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 .

When you need to collect data from users that matches options you set, use a selection input. To collect abstract data from users, use the text input widget instead.

JSON representation
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  }
}
Fields
name

string

The name by which the selection 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 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

enum ( SelectionType )

The way that an option appears to users. Different options support different types of interactions. For example, users can enable multiple check boxes, but can only select one value from a dropdown menu.

Each selection input supports one type of selection. Mixing check boxes and switches, for example, is not supported.

items[]

object ( SelectionItem )

An array of the selected items. For example, all the selected check boxes.

onChangeAction

object ( Action )

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 .

DateTimePicker

Lets users specify a date, a time, or both a date and a time.

Accepts text input from users, but features an interactive date and time selector that helps users enter correctly-formatted dates and times. If users enter a date or time incorrectly, the widget shows an error that prompts users to enter the correct format.

Not supported by Chat apps. Support by Chat apps coming soon.

JSON representation
{
  "name": string,
  "label": string,
  "type": enum (DateTimePickerType),
  "valueMsEpoch": string,
  "timezoneOffsetDate": integer,
  "onChangeAction": {
    object (Action)
  }
}
Fields
name

string

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

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

label

string

The text that prompts users to enter a date, time, or datetime.

Specify text that helps the user enter the information your app needs. For example, if users are setting an appointment, then a label like "Appointment date" or "Appointment date and time" might work well.

type

enum ( DateTimePickerType )

What kind of date and time input the datetime picker supports.

valueMsEpoch

string ( int64 format)

The value displayed as the default value before user input or previous user input, represented in milliseconds ( Epoch time ).

For DATE_AND_TIME type, the full epoch value is used.

For DATE_ONLY type, only date of the epoch time is used.

For TIME_ONLY type, only time of the epoch time is used. For example, to represent 3:00 AM, set epoch time to 3 * 60 * 60 * 1000 .

timezoneOffsetDate

integer

The number representing the time zone offset from UTC, in minutes. If set, the valueMsEpoch is displayed in the specified time zone. If not set, it uses the user's time zone setting on the client side.

onChangeAction

object ( Action )

Triggered when the user clicks Save or Clear from the datetime picker interface.