Toolbar

Toolbars provide a row of actions aligned horizontally with the Screen Header, such as toggles that switch between dashboard and table views.

  • Usage
  • Configuration
  • Examples

The Toolbar enables users to edit or otherwise take action on data in another component and is most commonly used in the same row as the Screen Header, though it can be used alongside other components as well. Users act on the content displayed by selecting actions. For example, the Toolbar could include a group of two actions that allow users to switch the way the data is displayed on the screen (i.e. from a dashboard view to a table view and vice-versa).

The functionality provided by the Toolbar is dependent on where it's included. A Toolbar added to a chart might enable users to download chart data, whereas a Toolbar added to the Screen Header might allow users to toggle between a dashboard and table view.

Anatomy

  1. Background color

  2. Active toggle

  3. Inactive toggle

  4. Group divider

  5. Action group

  6. Task menu

Best practices

  • Place view toggles all the way to the left in the Toolbar.
  • If a Toolbar contains an Action group (i.e. a menu kebab icon, which users select to access additional tasks), position it all the way to the right in the Toolbar.
  • Include no more than 3 groups in the Toolbar and no more than 3 tasks per group; limit the number of actions in a task menu to 9 (ideally in groups of 2).
  • Configure the Toolbar in a single column of the grid.
  • If additional tasks are needed, turn at least one group into the Action group.
  • Where space is limited, an Action group can be included as the only task.

Do

Limit the Toolbar to 3 groups of 3 actions per group.

Don't

Don't overwhelm the user with too many actions, or actions
not organized into groups.

Common patterns

With Screen Header

The Toolbar is a common addition to the Screen Header where basic functionality, such as collapse and expand, is added.

With Screen Breadcrumb

Toolbars are often added to screen breadcrumbs made using Screen Breadcrumb to allow users to toggle the display of content on the screen.

Properties

  • Groups section – Optional. A section of properties used to configure a toolbar group, including the available actions and how the buttons and icons for those actions function:
    • Name field – Required. The name of the task item.
    • Enable Group checkbox – Required. If selected, the action group is enabled. Defaults to selected.
    • Tasks section – Required. A section of properties used to configure an action:
      • Label field – Required. The label that displays for the action.
      • Icon field – Required. The UI icon that displays for the action.
      • Enable checkbox – Required. Specifies whether the action is enabled. Actions are enabled by default.
      • Select Initially checkbox – Optional. If selected, the action icon displays as selected when the screen loads. This property applies only to actions with a Type of Toggle.
      • Type drop-down – Optional. Specifies whether the action acts as a toggle switch or a standard action button:
        • Toggle – The action acts as a toggle switch.
        • Trigger – The action acts as a standard action button.
    • Use Action Menu checkbox – Optional. If selected, the toolbar displays as an Action Menu (i.e. as a single Action icon that displays a menu with each action when selected).
    • Show Icons in Action Menu checkbox – Optional. If selected, action icons display when the toolbar is in Action Menu form.
  • Background Color field – Optional. The hex code for the toolbar background color.
  • Icon Color field – Optional. The hex code for the action icon color in the toolbar.
  • Horizontal Alignment drop-down – Optional. Specifies the horizontal alignment of the toolbar:
    • Left – The toolbar displays left-aligned.
    • Center – The toolbar displays center-aligned.
    • Right – The toolbar displays right-aligned.

  • Visibility Permission field – Optional. The user's permission to access the component. If a user is not assigned a role that includes this permission, they cannot view or interact with the component.

  • Visibility Permission Not Assigned drop-down – Optional. If the user does not have permission to access the component, specifies whether to hide or disable it:
    • Hide – The component is hidden.
    • Disable – The component is visible but not cannot be interacted with.

Emitted events

  • On Task Select – The user selects an action.

Functions

  • Get State – When invoked in an event, returns the state of the action (i.e. whether the action is selected or not).
  • Get All Tasks – When invoked in an event, returns all actions.
  • Set Task State – When invoked in an event, activates a task, triggering the action's corresponding function.
  • Set Task State on Toggle – When invoked in an event, activates an action that is configured as a Toggle.

  • Set Task Icon on Task Select – When invoked in an event, activates an icon.

With groups

  • Groups:
    • Enable Group selected.
    • Tasks:
      • Type set to Toggle.
    • Use Action Menu selected.
    • Show Icons in Action Menu selected.
  • Background Color not included.
  • Icon Color not included.
  • Horizontal Alignment set to Right.

Without groups

  • Groups:
    • Enable Group not selected.
    • Tasks:
      • Type set to Toggle.
    • Use Action Menu not selected.
  • Background Color not included.
  • Icon Color not included.
  • Horizontal Alignment set to Right.