Context cards

A Gmail add-on appears in the Gmail UI as a pane in the sidebar (or, on mobile, as another activity window reached through the menu). The add-on has a top toolbar that identifies the add-on and displays a context card. Apps Script represents context cards in project code using Card objects.

Card anatomy

Example add-on card

A context card is a group of UI elements you design. A card consists of the following sections:

  • A card header. This identifies the cards. It has title text, and may optionally have a subtitle and an icon.
  • One or more card sections. These are sub-divisions of the card's UI area. A section may optionally have a text section header. Card sections are separated from each other on the card by a horizontal rule. If a card section is particularly large, it is automatically rendered as a collapsable section that users can expand or collapse as needed.
  • Each card section contains one or more UI widgets. Widgets provide the user with information or interactive controls. Cards and card sections are structural widgets, so you cannot add those to a card section.

You should design cards around particular user activities or data sets. For example, a Gmail add-on that displays data taken from Google Sheets might have a separate card for each sheet it pulls data from.

Using multiple cards

Example add-on card

It is possible to define more than one card for an add-on. You can either configure these cards as a simple list for basic navigation, or configure a more complex card stack navigation to control how the user moves between the cards.

If the add-on uses basic navigation, when the add-on is first opened Gmail constructs a list of the card headers and presents those to the user. Clicking on the card header opens that card. A back arrow is also provided to get back to the card header list. You do not have to code the header and back arrow functionality—this is done automatically when you define the cards in your add-on.

When designing add-ons, it's best to limit the number of cards you display at once, since cards must share a limited amount of screen space. It's also best to avoid unnecessary complexity in cards.