Toolbar - Web

For development, import Toolbar from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Toolbar consists of four primary elements that work together to group a set of controls.

Individual tools
Button
Select
Additional tools overflow menu

Options

The Toolbar supports the following configurations to accommodate various control grouping scenarios.

Direction

Direction	Description
Horizontal	The default behavior, which lays out tools horizontally.
Vertical	Lays out tools vertically.

Search Beta

Toolbar supports an optional search component that displays a Search Field for filtering or searching content. The Search Field should be placed on the left as the first item in the toolbar when used.

Size

Toolbar supports four size options that control the dimensions of all child components. The size propagates to buttons, toggles, links, and selects within the toolbar via context.

Size	Description
XSmall	Minimal sizing for highly compact or space-constrained layouts.
Small	Compact sizing for dense layouts or secondary toolbars.
Medium	The default size, suitable for most toolbar use cases.
Large	Larger sizing for increased touch targets or prominent toolbars.

Behavior

The Toolbar responds to space constraints with wrapping and collapse behaviors while maintaining consistent control grouping.

Wrapping

Overflow Handling	Description
Wrap	The default behavior, which wraps filters on resize.
Collapse	Collapses filters on resize behind an overflow menu.

Collapse Overflow

Overflow collapses in the same order as the DOM. The topmost item in the overflow menu is the first to reappear in the DOM when resizing to a wider width.

Usage Guidelines

Standard	Requirement
DoUse across WYSIWYGs and quick actions	Use Toolbar in multiple places such as WYSIWYGs, table quick actions, page header actions, or the Toolbelt experience.
DoProvide contextual actions below	Use Toolbar to provide contextual actions to users on the items below it, such as an emoji reaction to a comment or a font-styling option in a rich text editor.
Don’tUse for many actions	Avoid using Toolbar when there are many actions users can take on the items below. Use Toolbar to provide quick, contextual, and relevant actions.
Don’tBatch filter API calls	Avoid using Toolbar when you need to batch filter API calls based on user actions.
Don’tUse for complex filters	Avoid using Toolbar for complex filters.

Content

Content within the Toolbar should provide clear, contextual actions through grouped controls.

Keyboard Interaction

Users can navigate the Toolbar using standard keyboard controls.

Key	Interaction
Tab and Shift + Tab	Move focus into and out of the toolbar
Left Arrow / Up Arrow	Moves focus to the previous control. This wraps to last control if current control is the first. Note that this is on DOM level so direction doesn’t matter.
Right Arrow/ Down Arrow	Moves focus to the next control. This wraps to first control if current control is the last. Note that this is on DOM level so direction doesn’t matter.
Home	Moves focus to the first control
End	Moves focus to the last control

Accessibility

Keyboard interaction and aria guideline to follow WCAG Toolbar pattern. Since some ScreenReaders do not read disabled elements properly, we will enable focus for disabled controls using disabled as prop but internal assigning that to aria-disabled with style and function to block user interaction. For more guidance on form field labels and context, see input field context association best practices.

Code

Common Examples

import {Toolbar} from "@servicetitan/anvil2";

function ExampleComponent() {
  const selectItems = [
      ...
    ];

  const additionalItems = [
    ...
  ];

  return (
    <Toolbar
      associatedContent="..."
      additionalItems={additionalItems}
      overflow="collapse">
        <Toolbar.Button
          icon={...}
          onClick={...}
          aria-label="..."
        />

        <Toolbar.ButtonToggle
          onClick={...}>
          ...
        </Toolbar.ButtonToggle>

        <Toolbar.ButtonLink
          href={...}>
           ...
        </Toolbar.ButtonLink>

        <Toolbar.Select
          accessibleLabel="..."
          items={selectItems}
          onChange={...} />
    </Toolbar>
  )
}

The Anvil2 toolbar is made up a main Toolbar component and a few sub-components that can be used together to build simple or complex bars.

Toolbar: The parent component to configure toolbars.
Toolbar.Button: Used to create simple actions that need to be triggered via a button such as opening up a dialog.
Toolbar.ButtonToggle: Used to create simple actions that rely on a boolean response such as text font styles for a rich text editor.
Toolbar.ButtonLink: Used to create links to other sources such as download links.
Toolbar.Select: Used to create a single select drop down for items such as heading size selection for a rich text editor.
Toolbar.Search Beta: Used to create a search input field for filtering or searching content.

The components above should be the only items used within a toolbar to ensure look, feel, and overflow interactions remain consistent.When a page needs both toolbar actions and filters, compose Toolbar and FilterBar as siblings in a horizontal Flex row. Constrain the Toolbar with style={{ flex: "0 0 auto", width: "fit-content" }} and give FilterBar flexGrow={1} so the Toolbar does not expand and collapse the filters.See the FilterBar code docs for the full layout and keyboard details.The Toolbar.Search component provides a search input field for filtering or searching content within the context of a toolbar.

React Accessibility

Keyboard interaction and aria guideline to follow WCAG Toolbar pattern.
For controls that have the option to be icon only in view, aria-labels are required.
The Toolbar component has a required prop of associatedContent to properly populate an aria-label for the component itself.
Toolbar.Select has an accessibleLabel prop to properly link the list of select items to the trigger.
Toolbar.Search uses a search input with a clear button that is keyboard accessible via arrow keys.

For more guidance on form field labels and context, see input field context association best practices.

Testing

The toolbar’s leaf controls, overflow menu, and (in beta) search field carry a stable data-anv-part attribute so end-to-end tests can target them directly. The library owns the part names; you supply the instance identifier.Attach your own data-* attribute (such as data-cy or data-testid) to the Toolbar. It is forwarded to the root element, letting you scope queries to a single instance:

<Toolbar data-cy="editor-toolbar" associatedContent="document editor" {...rest} />

// Target a leaf button by part + accessible name
cy.get('[data-cy="editor-toolbar"] [data-anv-part="item"]').contains("Save").click();

// Open the overflow menu, then target a menu item
cy.get('[data-cy="editor-toolbar"] [data-anv-part="trigger"]').click();
cy.get('[data-anv-part="overflow-item"]').first().click();

Collapsed overflow items also carry data-id matching the item’s id, so you can target a specific row with [data-anv-part="overflow-item"][data-id="…"]. Discriminate repeated item parts with aria-label, id, or a consumer data-* on the leaf control.

`data-anv-part`	Element
`item`	A leaf `Toolbar.Button` / `Toolbar.ButtonToggle`
`trigger`	Overflow menu trigger button
`menu`	Overflow menu list (`role="menu"`)
`overflow-item`	A single overflow menu row (`role="menuitem"`)
`input`	Search field text input (`Toolbar.Search`, beta only)

Toolbar.ButtonLink and Toolbar.Select do not receive a library item part yet — pass your own data-* attributes on those components when you need to target them. Callers may override item (for example, FilterBar stamps trigger on boolean toggles).

The overflow menu renders in the browser’s top layer (menu and overflow-item parts), outside the Toolbar root. Descendant queries scoped to your wrapper attribute will not match those parts after the menu opens. Target them by their part attribute directly. Only one overflow menu is open at a time.

import { Toolbar } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Toolbar
      associatedContent="document editor"
      direction="horizontal"
      overflow="wrap"
      size="xsmall"
      additionalItems={[]}
    >
      {/* Toolbar content */}
    </Toolbar>
  );
}

string

required

Denotes what content the toolbar is associated with so that it can properly populate the aria-label.

ReactElement[]

Secondary actions that will be put in a menu at the end of the toolbar. While the type for this is a generic ReactElement, it is recommended that additional items only be Toolbar.Button, Toolbar.ButtonLink, Toolbar.ButtonToggle, and Toolbar.Select. Note: This menu also gets the items that get moved due to size constraints when the overflow is set to collapse.

"horizontal" | "vertical"

default:"horizontal"

Determines the direction the toolbar flows.Note: The direction determines which arrow keys are used for navigating through the toolbar via keyboard actions.

"wrap" | "collapse"

default:"wrap"

Determines if the toolbar controls will wrap to a new line when they run out of space or if they will be added to an overflow menu that gets appended to the end of the toolbar.

"xsmall" | "small" | "medium" | "large"

default:"xsmall"

Controls the size of all toolbar child components. The size propagates to all Toolbar.Button, Toolbar.ButtonToggle, Toolbar.ButtonLink, and Toolbar.Select items via context.

import { Toolbar } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<Toolbar.Button
  appearance="ghost"
  icon={Icon}
  aria-label="Button label"
  onClick={() => {}}
/>
); }

In addition to the props listed below, the Toolbar.Button component can accept any of the Button props with the exception of appearance, which is custom for this component.For accessibility compliance, if the button is icon-only, an aria-label becomes a required prop.

(e: MouseEvent) => void

required

Callback when the button is clicked.

"ghost" | "primary"

default:"ghost"

import { Toolbar } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Toolbar.ButtonLink
      appearance="ghost"
      href="/example"
    >
      Link Text
    </Toolbar.ButtonLink>
  );
}

In addition to the props listed below, the Toolbar.ButtonLink component can accept any of the ButtonLink props with the exception of appearance, which is custom for this component.

"ghost" | "primary"

default:"ghost"

import { Toolbar } from "@servicetitan/anvil2";

function ExampleComponent() {
return (

<Toolbar.ButtonToggle aria-label="Toggle label" defaultChecked={false}>
  Toggle
</Toolbar.ButtonToggle>
); }

The Toolbar.ButtonToggle component can accept any of the A2 ButtonToggle props, as well as any other HTML button props.Toolbar.ButtonToggle can be either controlled or uncontrolled.For accessibility compliance, if the button toggle is an icon only button an aria-label becomes a required prop.

import { Toolbar } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Toolbar.Select
      accessibleLabel="Select label"
      items={items}
      selected="item-1"
      appearance="ghost"
      onChange={(id) => console.log(id)}
    />
  );
}

The Toolbar.Select is comprised of an A2 Popover with an A2 Listbox for its dropdown.In addition to the props listed below, the Toolbar.Select can accept any of the A2 Popover Button props with the exceptions of appearance and onChange, which are custom for this component.

string

Label for the select that gets appended to aria tag for the select menu. Example: “State” becomes “State Options” for the select list label.

"ghost" | "primary"

default:"ghost"

ItemType & { id: string }[]

The options for the single select. The label is what will be visible in the option and in the select trigger upon selection.

(optionId: string) => void

Sets the selected item to your select as well as triggers any further onChange you pass to the component.

string

default:"first item id"

By default the first item in the items array is set to the selected item.

Beta

import { Toolbar } from "@servicetitan/anvil2/beta";

function ExampleComponent() {
  return (
    <Toolbar.Search
      placeholder="Search..."
      onChange={...}
      onClear={...}
    />
  );
}

The Toolbar.Search component is a specialized search input field designed for use within toolbars. It wraps the SearchField component and automatically inherits its size from the parent Toolbar context.In addition to the props listed below, the Toolbar.Search component can accept any of the standard HTML input attributes and SearchField props with the exception of size, which is inherited from the parent Toolbar.

string

default:"off"

Controls the browser’s autocomplete behavior for the search field.

string

Additional CSS classes to apply to the search field.

boolean

default:"false"

Whether the search field is disabled.

(e: ChangeEvent<HTMLInputElement>) => void

Callback function triggered when the input value changes.

() => void

Callback function triggered when the clear button is clicked or activated via keyboard (Enter or Space).

string

default:"Search..."

Placeholder text displayed when the input is empty.

string

The controlled value of the search field. Use with onChange for controlled components.

Concepts & Guidelines

Anvil2

Resources

Toolbar - Web

Anatomy

Options

Direction

Search Beta

Size

Behavior

Wrapping

Collapse Overflow

Usage Guidelines

Content

Keyboard Interaction

Accessibility

Accessibility

Code

Common Examples

React Accessibility

Testing

​Anatomy

​Options

​Direction

​Horizontal Toolbar

​Vertical Toolbar

​Search Beta

​Size

​Behavior

​Wrapping

​Toolbar with Wrapping Behavior

​Toolbar with Collapse Behavior

​Collapse Overflow

​Usage Guidelines

​Content

​Keyboard Interaction

​Accessibility

​Accessibility

​Code

​Common Examples

​Toolbar Components

​Using Toolbar with FilterBar Beta

​Using Toolbar.Search Beta

​React Accessibility

​Testing

​Toolbar Props

​Toolbar.Button Props

​Toolbar.ButtonLink Props

​Toolbar.ButtonToggle Props

​Toolbar.Select Props

​Toolbar.Search Props

Anatomy

Options

Direction

Horizontal Toolbar

Vertical Toolbar

Search Beta

Size

Behavior

Wrapping

Toolbar with Wrapping Behavior

Toolbar with Collapse Behavior

Collapse Overflow

Usage Guidelines

Content

Keyboard Interaction

Accessibility

Accessibility

Code

Common Examples

Toolbar Components

Using Toolbar with FilterBar Beta

Using Toolbar.Search Beta

React Accessibility

Testing

`Toolbar` Props

`Toolbar.Button` Props

`Toolbar.ButtonLink` Props

`Toolbar.ButtonToggle` Props

`Toolbar.Select` Props

`Toolbar.Search` Props