Patterns

Settings tables

Use tables to store lists of user-generated settings, rules and customizations.

As we add more and more customization, we are increasingly seeing a need to use tables to store lists of user-generated settings, rules and customizations. Currently this is happening with Approval Workflow settings, URL tracking settings and Custom Inbox Rules.

Examples

Approval Workflow Settings
Approval Workflows settings table.

URL Tracking Settings
URL Tracking settings.

General styles

Styles for text and borders (headers and cells) follow our existing styles for data tables in Reports.

Adding a new item

There should be a button above the table, right-aligned, enabling users to add another item. This should be a secondary-inverse button type with the fas circle+ icon.

  • Button label should follow the pattern “New [item name]
  • If a user does not have permission to add an item, the button should not be shown.
  • If a user has permission to add items, but they have reached their plan limit, the button should be shown in a disabled state, along with a message indicating that they have reached their limit.

Enable/disable item

If users are able to enable/disable items within the table, this should be controlled with a toggle component. The toggle should be the right-most column in the table and the column header should be “Enabled”.

Disabled State Should there be any additional “disabled styles” beyond the toggle?

Actions on items

Most tables will allow users to interact with items in the table. These can include actions like editing, duplicating and deleting items.

Simple action layout (preferred)

Whenever reasonable, settings tables should use icon-button components for actions. Icons should be displayed in a horizontal row, following rules found in our icons package. Each icon/action must have a tooltip/title indicating the action.

Actions in flyout

Actions can also be grouped into a flyout component and displayed as a list of text links. Use the dotdotdot icon to launch the flyout. This pattern can be used in the following circumstances:

  • There are more than 3 actions per item
  • Table width is an issue (too many columns, long text, etc)
  • One or more actions is semantically complex and would be difficult to communicate with an icon

Default Option

In some cases, we will want to allow users to select a single item from the table as a default option (primary example being approval workflows, where the default workflow is pre-selected in Compose for each new message).

If defaults are allowed, it should be indicated through a column labeled “Default”. If a default item is selected, it should be indicated in this column with the use of the star icon inside of a filled circle. All other items should display the circle icon instead. Titles/tooltips on these icons should indicate what will happen when they are clicked, in accordance with typical Icon-button standards.

Rules

  • Only one item can be the default at any given time. If the user sets an item as the default, any previously selected items should be de-selected (like a radio button).
  • A default is not required. User can de-select an existing default by clicking the star icon (unlike a radio button).
  • A disabled item cannot be the default. If the user disables an item selected as default, it becomes de-selected as default.