Examples
Toolbar items
A toolbar can contain multiple toolbar items, like filters and buttons.
Note: This example does not demonstrate responsive toolbar behavior. Responsive toolbars are shown in the examples with toggle groups and filters.
Toolbar item spacers
You may adjust the space between toolbar items to arrange them into groups. Read our spacers documentation to learn more about using spacers.
Items are spaced “16px” apart by default via their parents' gap or columnGap property. You can set the property values at multiple breakpoints, including "default", "md", "lg", "xl", and "2xl".
With adjusted inset
To adjust a toolbar’s inset, use the inset property. You can set the inset value at multiple breakpoints, including "default", "md", "lg, "xl", and "2xl". Inset values include “insetNone”, “insetSm”, “insetMd”, “insetLg”, “insetXl”, and “inset2xl”.
Sticky toolbar
To lock a toolbar and prevent it from scrolling with other content, use a sticky toolbar.
In the following example, toggle the "is toolbar sticky" checkbox to see the difference between a sticky and non-sticky toolbar.
With groups of items
You can group similar items together to create desired associations and to enable items to respond to changes in viewport width together.
Note: This example does not demonstrate responsive toolbar behavior. Responsive toolbars are shown in the examples with toggle groups and filters.
Examples with toggle groups and filters
The following examples use toggle groups to allow for more responsive and complex toolbars with multiple items and groups of items. To visualize responsive toolbar behavior in the following examples, resize the browser to a smaller screen width.
Component managed toggle groups
A toggle group allows you to collapse a set of items into an overlay panel at a certain breakpoint. For example, when a toggle group contains filter controls, its contents will collapse into an overlay panel when the toolbar adapts to a change in the viewport size. The contents can be toggled by selecting the filter icon in the overlay panel.
Consumer managed toggle groups
To manually create the expanded state of the toggle group for smaller screen widths:
- Add a
toggleIsExpandedcallback to the toolbar - Pass a boolean into the
isExpandedproperty of the toolbar
Note: The toggle group is aware of the consumer provided breakpoint, the expandable content is not. If the expandable content is expanded and the screen width surpasses that of the breakpoint, the expandable content is not aware of that and will remain open. Be sure to consider and handle this in your implementation.
With filters
You can add filters to a toolbar to let users filter the content that a toolbar manages. When a toolbar is filtered, it will expand in height to make space for a row of filter labels and a "Clear all filters" button. Upon clearing the applied filters, the toolbar will return to its default height.
The <ToolbarFilter> component expects applied filters and a delete label handler to be passed in as properties. Pass in a deleteLabelGroup property to close the entire label group. Once close, the rendering of labels will be handled responsively by the toolbar.
With custom label group content
To customize the label groups generated by toolbar filters, use the customLabelGroupContent property on the <Toolbar>. This property will remove the default clear all filters button.
Stacked example
Background color variants
To change the background color of a toolbar, use the colorVariant property on the <Toolbar>.
Props
Toolbar
| Name | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode | Content to be rendered as rows in the data toolbar | |
| className | string | Classes applied to root element of the data toolbar | |
| clearAllFilters | () => void | Optional callback for clearing all filters in the toolbar | |
| clearFiltersButtonText | string | Text to display in the clear all filters button | |
| collapseListedFiltersBreakpoint | 'all' | 'md' | 'lg' | 'xl' | '2xl' | The breakpoint at which the listed filters in label groups are collapsed down to a summary | |
| colorVariant | ToolbarColorVariant | 'default' | 'no-background' | 'primary' | 'secondary' | Background color variant of the toolbar | |
| customLabelGroupContent | React.ReactNode | Custom content appended to the filter generated label group. To maintain spacing and styling, each node should be wrapped in a ToolbarItem or ToolbarGroup. This property will remove the default "Clear all filters" button. | |
| id | string | Id of the data toolbar | |
| inset | { default?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; sm?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; md?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; lg?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; xl?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; '2xl'?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; } | Insets at various breakpoints. | |
| isExpanded | boolean | Flag indicating if a data toolbar toggle group's expandable content is expanded | |
| isFullHeight | boolean | Flag indicating the toolbar height should expand to the full height of the container | |
| isStatic | boolean | Flag indicating the toolbar is static | |
| isSticky | boolean | Flag indicating the toolbar should stick to the top of its container | |
| numberOfFiltersText | (numberOfFilters: number) => string | Text to display in the total number of applied filters ToolbarFilter | |
| ouiaId | number | string | Value to overwrite the randomly generated data-ouia-component-id. | |
| ouiaSafe | boolean | Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false. | |
| toggleIsExpanded | () => void | A callback for setting the isExpanded flag |
ToolbarContent
| Name | Type | Default | Description |
|---|---|---|---|
| alignItems | 'start' | 'center' | 'baseline' | 'default' | Vertical alignment of children | |
| children | React.ReactNode | Content to be rendered as children of the content row | |
| className | string | Classes applied to root element of the data toolbar content row | |
| clearAllFilters | () => void | Optional callback for clearing all filters in the toolbar | |
| clearFiltersButtonText | string | Text to display in the clear all filters button | |
| isExpanded | boolean | false | Flag indicating if a data toolbar toggle group's expandable content is expanded |
| showClearFiltersButton | boolean | false | Flag indicating that the clear all filters button should be visible |
| toolbarId | string | Id of the parent Toolbar component | |
| visibility | { default?: 'hidden' | 'visible'; md?: 'hidden' | 'visible'; lg?: 'hidden' | 'visible'; xl?: 'hidden' | 'visible'; '2xl'?: 'hidden' | 'visible'; } | Visibility at various breakpoints. |
ToolbarGroup
| Name | Type | Default | Description |
|---|---|---|---|
| align | { default?: 'alignEnd' | 'alignStart' | 'alignCenter'; md?: 'alignEnd' | 'alignStart' | 'alignCenter'; lg?: 'alignEnd' | 'alignStart' | 'alignCenter'; xl?: 'alignEnd' | 'alignStart' | 'alignCenter'; '2xl'?: 'alignEnd' | 'alignStart' | 'alignCenter'; } | Applies to a child of a flex layout, and aligns that child (and any adjacent children on the other side of it) to one side of the main axis | |
| alignItems | 'start' | 'center' | 'baseline' | 'default' | 'end' | 'stretch' | Vertical alignment of children | |
| alignSelf | 'start' | 'center' | 'baseline' | 'default' | 'end' | 'stretch' | Vertical alignment | |
| children | React.ReactNode | Content to be rendered inside the data toolbar group | |
| className | string | Classes applied to root element of the data toolbar group | |
| columnGap | { default?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; md?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; lg?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; xl?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; '2xl'?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; } | Sets only the column gap at various breakpoints. | |
| gap | { default?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; md?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; lg?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; xl?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; '2xl'?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; } | Sets both the column and row gap at various breakpoints. | |
| isOverflowContainer | boolean | Flag that modifies the toolbar group to hide overflow and respond to available space. Used for horizontal navigation. | |
| rowGap | { default?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; md?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; lg?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; xl?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; '2xl'?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; } | Sets only the row gap at various breakpoints. | |
| variant | | ToolbarGroupVariant | 'filter-group' | 'action-group' | 'action-group-inline' | 'action-group-plain' | 'label-group' | A type modifier which modifies spacing specifically depending on the type of group | |
| visibility | { default?: 'hidden' | 'visible'; md?: 'hidden' | 'visible'; lg?: 'hidden' | 'visible'; xl?: 'hidden' | 'visible'; '2xl'?: 'hidden' | 'visible'; } | Visibility at various breakpoints. |
ToolbarItem
| Name | Type | Default | Description |
|---|---|---|---|
| align | { default?: 'alignEnd' | 'alignStart' | 'alignCenter'; md?: 'alignEnd' | 'alignStart' | 'alignCenter'; lg?: 'alignEnd' | 'alignStart' | 'alignCenter'; xl?: 'alignEnd' | 'alignStart' | 'alignCenter'; '2xl'?: 'alignEnd' | 'alignStart' | 'alignCenter'; } | Applies to a child of a flex layout, and aligns that child (and any adjacent children on the other side of it) to one side of the main axis | |
| alignItems | 'start' | 'center' | 'baseline' | 'default' | 'end' | 'stretch' | Vertical alignment of children | |
| alignSelf | 'start' | 'center' | 'baseline' | 'default' | 'end' | 'stretch' | Vertical alignment | |
| children | React.ReactNode | Content to be rendered inside the data toolbar item | |
| className | string | Classes applied to root element of the data toolbar item | |
| columnGap | { default?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; md?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; lg?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; xl?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; '2xl'?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; } | Sets only the column gap at various breakpoints. | |
| gap | { default?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; md?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; lg?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; xl?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; '2xl'?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; } | Sets both the column and row gap at various breakpoints. | |
| id | string | id for this data toolbar item | |
| isAllExpanded | boolean | Flag indicating if the expand-all variant is expanded or not | |
| isOverflowContainer | boolean | Flag that modifies the toolbar item to hide overflow and respond to available space. Used for horizontal navigation. | |
| rowGap | { default?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; md?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; lg?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; xl?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; '2xl'?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; } | Sets only the row gap at various breakpoints. | |
| variant | ToolbarItemVariant | 'pagination' | 'label' | 'label-group' | 'separator' | 'expand-all' | A type modifier which modifies spacing specifically depending on the type of item | |
| visibility | { default?: 'hidden' | 'visible'; md?: 'hidden' | 'visible'; lg?: 'hidden' | 'visible'; xl?: 'hidden' | 'visible'; '2xl'?: 'hidden' | 'visible'; } | Visibility at various breakpoints. |
ToolbarToggleGroup
| Name | Type | Default | Description |
|---|---|---|---|
| breakpointrequired | 'md' | 'lg' | 'xl' | '2xl' | Controls when filters are shown and when the toggle button is hidden. | |
| toggleIconrequired | React.ReactNode | An icon to be rendered when the toggle group has collapsed down | |
| clearAllFilters | () => void | Optional callback for clearing all filters in the toolbar toggle group | |
| clearFiltersButtonText | string | Text to display in the clear all filters button of the toolbar toggle group | |
| columnGap | { default?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; md?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; lg?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; xl?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; '2xl'?: | 'columnGapNone' | 'columnGapXs' | 'columnGapSm' | 'columnGapMd' | 'columnGapLg' | 'columnGapXl' | 'columnGap_2xl' | 'columnGap_3xl' | 'columnGap_4xl'; } | Sets only the column gap at various breakpoints. | |
| gap | { default?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; md?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; lg?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; xl?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; '2xl'?: 'gapNone' | 'gapXs' | 'gapSm' | 'gapMd' | 'gapLg' | 'gapXl' | 'gap_2xl' | 'gap_3xl' | 'gap_4xl'; } | Sets both the column and row gap at various breakpoints. | |
| isExpanded | boolean | Flag indicating when toggle group is expanded for non-managed toolbar toggle groups. | |
| labelContainerRef | React.RefObject<any> | Reference to a label container group for filters inside the toolbar toggle group | |
| onToggle | (event: React.MouseEvent) => void | Callback for toggle group click event for non-managed toolbar toggle groups. | |
| rowGap | { default?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; md?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; lg?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; xl?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; '2xl'?: | 'rowGapNone' | 'rowGapXs' | 'rowGapSm' | 'rowGapMd' | 'rowGapLg' | 'rowGapXl' | 'rowGap_2xl' | 'rowGap_3xl' | 'rowGap_4xl'; } | Sets only the row gap at various breakpoints. | |
| showClearFiltersButton | boolean | Flag indicating that the clear all filters button should be visible in the toolbar toggle group | |
| visibility | { default?: 'hidden' | 'visible'; md?: 'hidden' | 'visible'; lg?: 'hidden' | 'visible'; xl?: 'hidden' | 'visible'; '2xl'?: 'hidden' | 'visible'; } | Visibility at various breakpoints. |
ToolbarFilter
| Name | Type | Default | Description |
|---|---|---|---|
| categoryNamerequired | string | ToolbarLabelGroup | Unique category name to be used as a label for the label group | |
| childrenrequired | React.ReactNode | Content to be rendered inside the data toolbar item associated with the label group | |
| deleteLabel | (category: string | ToolbarLabelGroup, label: ToolbarLabel | string) => void | Callback passed by consumer used to delete a label from the labels[] | |
| deleteLabelGroup | (category: string | ToolbarLabelGroup) => void | Callback passed by consumer used to close the entire label group | |
| expandableLabelContainerRef | React.RefObject<HTMLDivElement> | Reference to a label container created with a custom expandable content group, for non-managed multiple toolbar toggle groups. | |
| isExpanded | boolean | Flag indicating when toolbar toggle group is expanded for non-managed toolbar toggle groups. | |
| labelGroupCollapsedText | string | Customizeable template string for the label group. Use variable "${remaining}" for the overflow label count. | |
| labelGroupExpandedText | string | Customizable "Show Less" text string for the label group | |
| labels | (string | ToolbarLabel)[] | [] | An array of strings to be displayed as labels in the expandable content |
| showToolbarItem | boolean | true | Flag to show the toolbar item |
CSS variables
| Expand or collapse column | Selector | Variable | Value |
|---|
