Widgets

A widget is a simple 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. The widgets have the same appearance and function on both web and mobile devices. The reference documentation describes a number of methods for building widget sets.

Use the Google WorkspaceAdd-ons design kit

To save time designing an add-on's widgets, designers can use the Google Workspaceadd-ons UI design kit available on Figma. You can create a free Figma account, or request a license from your organization's administrator.

Browse the components and use built-in templates to create and visualize widgets.

Get the design kit

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 AI.

Structural widgets

  • 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. You define how users can 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 the add-on uses them.
  • Card section—A collected group of widgets, divided from the other card sections by a horizontal rule and optionally having a section header. Each card must have at least one card section. You cannot add cards or card headers to a card section.

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

You can now 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. 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("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

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

 

 Fixed footer widget example

Peek card

Peek card example

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, instead of immediately displaying the new contextual content, 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 immediately 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.

The following code, based on the Cats Google Workspaceadd-on quickstart, 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')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);

 

 Customized peek card example

Informational widgets

Informational widgets

Informational widgets present information to the user.

  • Image—An image indicated by a hosted and publicly accessbile URL you provide.
  • DecoratedText—A text content string that you can pair with other elements such as top and bottom text labels, and an image or icon. DecoratedText widgets can also include a Button or Switch widget. Added switches can be simple toggles or checkboxes. The content text of the DecoratedText widget can use HTML formatting; the top and bottom labels must use plain text.
  • Text paragraph—A simple text paragraph, which can include HTML formatted elements.




User interaction widgets

Card action widget

User interaction widgets allow the add-on to respond to actions taken by the users. You can configure these widgets with action responses to display different cards, open URLs, show notifications, compose draft emails, or run other Apps Script functions. See the Building Interactive Cards guide for details.

User interaction widgets

  • Card action—A menu item placed in the add-on header bar menu. The header bar menu can also contain items defined as universal actions, which appear on every card the add-on defines.
  • DateTime pickers—widgets that allow users to select a date, time, or both. See Date and time pickers below for more information.
  • Image button—A button that uses an image instead of text. You can use one of several pre-defined icons or a publicly-hosted image indicated by its URL.
  • Selection input—An input field that represents a collection of options. Selection input widgets present as checkboxes, radio buttons or drop-down selection boxes.
  • Switch—A toggle widget. You can only use switches in conjunction with a DecoratedText widget. By default these display as a toggle switch, but you can cause them to display as a checkbox instead.
  • Text button—A button with a text label. You can specify a background color fill for text buttons (the default is transparent). You can also disable the button as needed.
  • Text input—A text input field. The widget can have title text, hint text and multiline text. The widget can trigger actions when the text value changes.
  • Grid—A multi-column layout that represents a collection of items. You can represent items with an image, title, subtitle, and a range of customization options such as border and crop styles.

DecoratedText checkboxes

You can define a DecoratedText widget that has a checkbox attached, instead of a button or binary toggle switch. Like with switches, the value of the checkbox is included in the action event object that is passed to the Action attached to this DecoratedText by the setOnClickAction(action) method.

The following code excerpt shows how to define a checkbox DecoratedText widget, which you can then add to a card:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

 

 Decorated-text checkbox widget example

Date and time pickers

You can define widgets that allow users to select a time, a date, or both. You can use setOnChangeAction() to assign a widget handler function to execute when the value of the picker changes.

The following code excerpt shows how to define a date-only picker, a time-only picker, and a date-time picker, which you can then add to a card:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the date.")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter the time.")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter the date and time in EDT time.")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));

 

 Customized peek card example

The following is an example of a date-time picker widget handler function. This handler simply formats and logs a string representing the date-time chosen by the user in a date-time picker widget with the ID "myDateTimePickerWidgetID":

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

 

The table below shows examples of the picker selection UIs on desktop and mobile devices. When selected, the date picker opens a month-based calendar UI to allow the user to quickly select a new date.

When the user selects the time picker on desktop devices, a drop-down menu opens with a list of times separated in 30 minute increments that the user can select from. The user can also type in a specific time. On mobile devices selecting a time picker opens the built-in mobile "clock" time picker.

Desktop Mobile
date picker selection example mobile date picker selection example
time picker selection example mobile time picker selection example

Grid

Display items in a multi-column layout with the grid widget. Each item can display an image, title, and subtitle. Use additional configuration options to set the positioning of text relative to the image in a grid item.

You can configure a grid item with an identifier that’s returned as a parameter to the action defined on the grid.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

 

 Grid widget example

Text formatting

Some text-based widgets can support simple text HTML formatting. When setting the text content of these widgets, just include the corresponding HTML tags. The following formats are supported:

Format Example Rendered Result
Bold <b>test</b> test
Italics <i>test</i> test
Underline <u>test</u> test
Strikethrough <s>test</s> test
Font color <font color="#ea9999">test</font> test
Hyperlink <a href="http://www.google.com">google</a> google
Time <time>2020-02-16 15:00</time> 2020-02-16 15:00
Newline test <br> test test
test