Widgets

  • Widgets are UI elements that provide structure, information, and actions within Google Workspace add-ons.

  • There are three main widget categories: structural, informational, and user interaction widgets, each with various specific widget types.

  • Cards, sections, and headers are structural widgets used to organize and contain other widgets, supporting navigation and layout functionalities.

  • Informational widgets like images, decorated text, and paragraphs present data to the user, supporting HTML formatting for enhanced visual representation.

  • User interaction widgets enable user input and actions, triggering responses like opening links, running functions, or displaying new content through elements like buttons, input fields, and selection inputs.

A widget is a UI element that provides one or more of the following:

  • Structure for other widgets such as cards and sections,
  • Information to the user such as text and images, or
  • Affordances for action such as buttons, text input fields, or checkboxes.

Sets of widgets added to card sections define the overall add-on UI. Widgets have the same appearance and function on both web and mobile devices. The reference documentation describes several methods for building widget sets.

Widget types

Add-on widgets are generally categorized into three groups: structural widgets, informational widgets, and user interaction widgets.

Structural widgets

Structural widgets provide containers and organization for the other widgets used in the UI.

  • Button set: A collection of one or more text or image buttons, grouped together in a horizontal row.
  • Card: A single context card that contains one or more card sections. Define how users move between cards by configuring card navigation.
  • Card header: The header for a given card. Card headers can have titles, subtitles, and an image. Card actions and universal actions appear in the card header if used.
  • Card section: A collected group of widgets, divided from other card sections by a horizontal rule and optionally having a section header. Each card must have at least one card section. You can't add cards or card headers to a card section.

Example of a card showing structural widgets

When you add a widget to one of the containers, you create and add a copy of that widget. If you change the widget after adding it, the change isn't reflected in the interface. Ensure the widget is complete before adding it. If you need to change a widget after adding it, rebuild the entire card section or card. See Construct cards for more details.

In addition to these basic structural widgets, in a Google Workspace add-on you can use the Card service to create structures that overlap the current card: fixed footers and peek cards:

You can add a fixed row of buttons to the bottom of your card. This row doesn't move or scroll with the rest of the card content.

Fixed footer widget example

The following code excerpt shows how to define an example fixed footer and add it to a card:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

Peek card

Example of a peek card notification

When new contextual content is triggered by a user action, such as opening a Gmail message, you can either display the new contextual content immediately (default behavior) or display a peek card notification at the bottom of the sidebar. If a user clicks Back to return to your homepage while a contextual trigger is active, a peek card appears to help users find the contextual content again.

To display a peek card when new contextual content is available, add .setDisplayStyle(CardService.DisplayStyle.PEEK) to your CardBuilder class. A peek card only appears if a single card object is returned with your contextual trigger; otherwise, the returned cards replace the current card.

To customize the peek card's header, add the .setPeekCardHeader method with a standard CardHeader object when building your contextual card. By default, a Peek card header contains only the name of your add-on. Customized peek card example

Based on the Cats Google Workspace add-on quickstart, the following code notifies users about new contextual content with a Peek card and customizes the Peek card's header to display the selected Gmail message thread's subject.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat'