Format the structure of a card or dialog

This page explains how to format and structure widgets in a card or dialog message.


Design and preview cards with the Card Builder.

Open the Card Builder

Prerequisites

  • A Google Workspace account with access to Google Chat.
  • A published Chat app. To build a Chat app, follow this quickstart.
  • Display cards and dialogs in columns

    The columns widget displays up to 2 columns in a card or dialog. You can add widgets to each column; the widgets appear in the order that they're' specified. To include more than 2 columns, or to use rows, use the grid widget.

    The height of each column is determined by the taller column. For example, if the first column is taller than the second column, both columns have the height of the first column. Because each column can contain a different number of widgets, you can't define rows or align widgets between the columns.

    The following example displays a card with a columns widget that features 2 columns of text. To view only the columns layout and to collapse the code sample, click Collapse. When space is constrained, like in the following example, the second column wraps below the first column.

    Define the width of a column

    Columns are displayed side-by-side. You can customize the width of each column using the horizontalSizeStyle field. If the user's screen width is too narrow, the second column wraps below the first:

    • On web, the second column wraps if the screen width is less than or equal to 480 pixels.
    • On iOS devices, the second column wraps if the screen width is less than or equal to 300 pt.
    • On Android devices, the second column wraps if the screen width is less than or equal to 320 dp.

    The following example displays a card with a columns widget that features 2 columns of text with 4 items in the columns. Each item in the columns has horizontalSizeStyle applied in order to manipulate how much space the text fills each column:

    • The first text paragraph uses FILL_MINIMUM_SPACE to fill no more than 30% of the cards's width.
    • The second text paragraph uses FILL_AVAILABLE_SPACE to fill the available space in the card's width. In this example, it fills 70% of the card's width.
    • The third text paragraph doesn't define horizontalSizeStyle so it defaults to fill the available space of the card's space.
    • The fourth text paragraph uses FILL_MINIMUM_SPACE to fill no more than 30% of the cards's width.

    Define the horizontal alignment of a column

    You can align widgets horizontally to the left, right, or center of a column by defining the horizontalAligment field. If the horizontalAlignment fiield is undefined, widgets are aligned to the left in column.

    The following example horizontally aligns text within a column to the left:

    The following example horizontally aligns text within a column in the center:

    The following example horizontally aligns text within a column to the right:

    Define the vertical alignment of a column

    You can align widgets vertically to the top, bottom, or center of a column by defining the verticalAlignment field. If the verticalAlignment field is undefined, widgets in a column are aligned to the top.

    The following example vertically aligns text within a column to the top:

    The following example vertically aligns text within a column in the center:

    The following example vertically aligns text within a column in the bottom:

    Add a horizontal divider between widgets

    The divider widget displays a horizontal line spanning the width of a card between vertically stacked widgets. The line is a visual divider that helps users distinguish between one widget and another, making cards easier to scan and understand.

    The following is a card consisting of divider widget between other types of widgets:

    Display a grid with a collection of items

    The grid widget displays a grid with a collection of items. A grid supports any number of columns and items. The number of rows is determined by items divided by columns. A grid with 10 items and 2 columns has 5 rows. A grid with 11 items and 2 columns has 6 rows.

    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.

    The following example is a 2 column grid with a single item:

    Define where text appears with an image in a grid

    The gridItemLayout field lets you define within each gridItem, whether the text appears above or below the item in the grid. If gridItemLayout is undefined, the text defaults to appear below the item in the grid

    The following example is a 3 column grid with text and an image in each grid. The first grid defines text to appear above the image, the second grid defines text to appear below the image, and the third grid doesn't define the position of the text.

    Add a border to UI elements

    For items that appear in a column or a grid widget, you can add a border to these UI elements by defining a borderType field and a borderStyle field. If no borderStyle field is defined, it defaults to showing no border. You can define a borderType to apply to all items within a widget or apply the styling to each individual item within a widget.

    The following example is a 2 column grid with an image in each grid where the border type, style, and color has been defined to apply to all items within the grid.

    The following example is a 3 column grid with an image in each grid and the border style and type defined individually. The first image has a border defined as STROKE. The second image has a border defined as NO_BORDER. The third image has no border defined.

    Troubleshoot

    When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

    Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, see Troubleshoot and fix Google Chat errors.