Toolbar – 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.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.

Anvil2 Web

Resources

Toolbar – Code

Common Examples

React Accessibility

Testing

​Common Examples

​Toolbar Components

​Using Toolbar.Search Beta

​React Accessibility

​Testing

​Toolbar Props

​Toolbar.Button Props

​Toolbar.ButtonLink Props

​Toolbar.ButtonToggle Props

​Toolbar.Select Props

​Toolbar.Search Props

Common Examples

Toolbar Components

Using Toolbar.Search Beta

React Accessibility

Testing

`Toolbar` Props

`Toolbar.Button` Props

`Toolbar.ButtonLink` Props

`Toolbar.ButtonToggle` Props

`Toolbar.Select` Props

`Toolbar.Search` Props