AI-generated Key Takeaways
-
Google Workspace add-ons utilize cards, essentially UI pages, displayed in a sidebar or activity window, to present information and interactive elements.
-
Each card is structured with a header, sections containing widgets (like buttons or text fields), and is designed around specific user tasks or data sets.
-
Add-ons often employ multiple cards for navigation; basic navigation provides an automatic card header list and back arrow functionality.
-
For optimal performance and user experience, it's recommended to keep the number of cards, sections, and widgets to a minimum, prioritizing simplicity in card design.
-
Cards have technical limitations, restricting them to a maximum of 100 card sections and 100 widgets per section to maintain performance.
A card-based add-on appears 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 card—essentially a "page" of the
add-on's UI. Apps Script represents cards in project code using
Card objects.
Card anatomy
A 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 collapsible section that users can expand or collapse as needed. A card can have no more than 100 card sections, and should have only a few for better performance.
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. A card section can have no more than 100 widgets, and should be as simple as possible for best performance.
You should design cards around particular user activities or data sets. For example, a Google Workspace add-on that displays data taken from Google Sheets might have a separate card for each sheet it pulls data from.
Using multiple cards
Add-ons usually consist of more than one card. You can either configure these cards as a simple list for basic navigation with multiple cards, or configure more complex navigation methods to control how the user moves between the cards.
If the add-on uses basic navigation, when the add-on is first opened the Google Workspace application it extends 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.