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.
Add-on widgets are generally categorized into three groups: structural widgets, informational widgets, and user interaction widgets.
Structural widgets provide containers and organization for the other widgets used in the AI.
- 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.
Informational widgets present information to the user.
- Image—An image indicated by a hosted and publicly accessbile URL you provide.
- Key-Value—A text content string that you can pair with other elements such as top and bottom text labels, and an image or icon. Key-value widgets can also include a Button or Switch widget. The text content of the Key Value widget can use HTML formatting.
- Text Paragraph—A simple text paragraph, which can include HTML formatted elements.
User interaction widgets
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.
- 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.
- 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 switch widget. You can only use switches in conjunction with a Key-Value widget.
- 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.
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: