Toolbar
Toolbars provide access to functions related to a single screen or container within a screen. They may appear in Tables, Panels, and other content containers where complex functionality is needed to manipulate data and content.
Icon Example
When to Use
- Use when a set of actions are needed within the context of a page, panel, table, tab set
- Use icons when their meaning is understood by users and space is at a premium.
When Not to Use
- Do not use for navigation or links; the toolbar is reserved for actions.
Variations
- Icon Example (shown above)
- Limited Horizontal Space Icon Example
- Text Example
- Limited Horizontal Space Text Example
Usage
Text vs Icon Controls
- Use text labels or icons (but not both) in the context of the visible toolbar controls.
- Text may be combined with icons in the “more actions” menu. When present, the “more actions” menu appears on the far right.
- When text and icons are combined in the “more actions” menu, the icons are right-aligned within the popover.
Display and Behavior
- Display a maximum of 4-6 actions within the visible portion of the toolbar (on large/xl screens). This will scale down on smaller resolutions and controls will shift into the “more actions” menu as available horizontal space decreases.
- By default, the toolbar will prioritize the visibility of controls starting from the left. You may also override this behavior by using the
[data-priority]property to ensure high-priority element are collapsed last, regardless of their order in the toolbar items. You can override the default ordering of items by applying a[data-order]integer value. - The above order is maintained unless an item is too large to fit in the remaining space, then it will skip to the next item to fit as many items as possible.
- The toolbar dynamically fits as many controls as possible into the visible container until the small breakpoint is reached, where all items will be placed into the “more actions” menu.
- In examples it is shown alongside a title with vertical-centering but can used completely stand-alone.
Level of Actions
- A control may prompt an action to occur immediately OR it may display a series of additional actions in a Popover menu or Modal.
- When expanded, the “view more” menu displays a single level of actions. Each action within this menu may expand to display a second level of sub-actions. Additional levels beyond two should be handled via a modal window accessed from the toolbar.
Variations
Limited Horizontal Space Icon Example
Text Button Toolbar
This toolbar use only text buttons in the visible portion. Icons may be included alongside the text in the “more actions” menu.
When to Use
- When your descriptive labels are more important than conserving space, and horizontal space is plentiful.
- Use if toolbar actions require a descriptive label to understand what the action does
When Not to Use
- Do not use if horizontal space is limited
Additional Guidelines
- For semantic markup, an H5 may be required for the heading alongside a Text Button Toolbar. In these instances, CSS should be used to change the visual style of the heading to resemble an H4 or higher, as the H5 font style lacks visual distinction from the actionable elements in the toolbar.
Limited Horizontal Space Text Example
Developer Notes
- You can switch to the Icon Toolbar by adding the class
spark-toolbar--iconto the.spark-toolbarelement. - You can selectively give toolbar items a Tooltip, the tooltip will not be displayed for items inside the show-more dropdown.
- You can set the contents of a dropdown to close the dropdown (and the show-more menu) by giving whichever element should close the dropdown the class
spark-toolbar__item--close-on-click. - Toolbar items that do not have
.spark-toolbar__item--contentwill cause the show-more menu to close when they are selected. - Any content can be placed inside the
.spark-toolbar__item--content, but the width for these dropdowns are fixed at24rem, with a default2rem 1rempadding applied when using aul.spark-toolbar__listor.spark-toolbar__item--content__container. The recommended default dropdown would be adiv.spark-toolbar__item--content.spark-toolbar__item--content__container. - A styled checkbox list is also available when using a
ul.spark-toolbar__list.spark-toolbar__list--checkboxesinside, or as, the.spark-toolbar__item--content. - Calling the
change()function on the Toolbar instance will cause a recalculation of the toolbar, you should call this function after programmatically adding, removing, or modifying the toolbar’s items or styling. - You can optionally specify a
[data-priority]integer property on.spark-toolbar__items that will determine the order in which toolbar items should be collapsed into the show-more menu. Higher priority values will be collapsed last. - You can optionally specify an
[data-order]integer property on.spark-toolbar__items that will determine the order in which toolbar items are ordered. When initialized the original order in the document is set as the default ordering. When adding.spark-toolbar__items programmatically, then using thechange()function to recalculate appearance, the new items will default to the front of the list, unless specified using.spark-toolbar__item[data-order]property.
The following options may be passed when using new Spark.Toolbar(el, {});:
| Name | Type | Default | Description |
|---|---|---|---|
| onClick | function | noop() | A callback function run when a Toolbar item is clicked. Callback arguments are toolbarItemEl, instance. |
For all available methods and full API, refer to the component code on Bitbucket.