Base UI

A container for grouping a set of buttons and controls.

import * as React from 'react';
import { Toolbar } from '@base-ui-components/react/toolbar';
import { ToggleGroup } from '@base-ui-components/react/toggle-group';
import { Toggle } from '@base-ui-components/react/toggle';
import { Select } from '@base-ui-components/react/select';
import styles from './index.module.css';

export default function ExampleToolbar() {
  return (
    <Toolbar.Root className={styles.Toolbar}>
      <ToggleGroup className={styles.Group} aria-label="Alignment">
        <Toolbar.Button
          render={<Toggle />}
          aria-label="Align left"
          value="align-left"
          className={styles.Button}
        >
          Align Left
        </Toolbar.Button>
        <Toolbar.Button
          render={<Toggle />}
          aria-label="Align right"
          value="align-right"
          className={styles.Button}
        >
          Align Right
        </Toolbar.Button>
      </ToggleGroup>
      <Toolbar.Separator className={styles.Separator} />
      <Toolbar.Group className={styles.Group} aria-label="Numerical format">
        <Toolbar.Button className={styles.Button} aria-label="Format as currency">
          $
        </Toolbar.Button>
        <Toolbar.Button className={styles.Button} aria-label="Format as percent">
          %
        </Toolbar.Button>
      </Toolbar.Group>
      <Toolbar.Separator className={styles.Separator} />
      <Select.Root defaultValue="Helvetica">
        <Toolbar.Button render={<Select.Trigger />} nativeButton={false} className={styles.Button}>
          <Select.Value />
          <Select.Icon className={styles.SelectIcon}>
            <ChevronUpDownIcon />
          </Select.Icon>
        </Toolbar.Button>
        <Select.Portal>
          <Select.Positioner className={styles.Positioner} sideOffset={8}>
            <Select.Popup className={styles.Popup}>
              <Select.Item className={styles.Item} value="Helvetica">
                <Select.ItemIndicator className={styles.ItemIndicator}>
                  <CheckIcon className={styles.ItemIndicatorIcon} />
                </Select.ItemIndicator>
                <Select.ItemText className={styles.ItemText}>Helvetica</Select.ItemText>
              </Select.Item>
              <Select.Item className={styles.Item} value="Arial">
                <Select.ItemIndicator className={styles.ItemIndicator}>
                  <CheckIcon className={styles.ItemIndicatorIcon} />
                </Select.ItemIndicator>
                <Select.ItemText className={styles.ItemText}>Arial</Select.ItemText>
              </Select.Item>
            </Select.Popup>
          </Select.Positioner>
        </Select.Portal>
      </Select.Root>
      <Toolbar.Separator className={styles.Separator} />
      <Toolbar.Link className={styles.Link} href="#">
        Edited 51m ago
      </Toolbar.Link>
    </Toolbar.Root>
  );
}

function ChevronUpDownIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="8"
      height="12"
      viewBox="0 0 8 12"
      fill="none"
      stroke="currentcolor"
      strokeWidth="1.5"
      {...props}
    >
      <path d="M0.5 4.5L4 1.5L7.5 4.5" />
      <path d="M0.5 7.5L4 10.5L7.5 7.5" />
    </svg>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

Accessibility guidelines

To ensure that toolbars are accessible and helpful, follow these guidelines:

Use inputs sparingly: Left and right arrow keys are used to both move the text insertion cursor in an input, and to navigate among controls in horizontal toolbars. When using an input in a horizontal toolbar, use only one and place it as the last element of the toolbar.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Toolbar } from '@base-ui-components/react/toolbar';

<Toolbar.Root>
  <Toolbar.Button />
  <Toolbar.Link />
  <Toolbar.Separator />
  <Toolbar.Group>
    <Toolbar.Button />
    <Toolbar.Button />
  <Toolbar.Group />
  <Toolbar.Input />
</Toolbar.Root>

API reference

Root

A container for grouping a set of controls, such as buttons, toggle groups, or menus. Renders a <div> element.

cols

number

(default:

1

)

Name: cols
Description: The number of columns. When greater than 1, the toolbar is arranged into a grid.
Type: number | undefined
Default: 1

disabled

boolean

Name: disabled
Type: boolean | undefined

loop

boolean

(default:

true

)

Name: loop
Description: If true, using keyboard navigation will wrap focus to the other end of the toolbar once the end is reached.
Type: boolean | undefined
Default: true

orientation

Toolbar.Root.Orientation

(default:

'horizontal'

)

Name: orientation
Description: The orientation of the toolbar.
Type: 'horizontal' | 'vertical' | undefined
Default: 'horizontal'

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toolbar.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toolbar.Root.State, ) => ReactElement)

data-orientation

Indicates the orientation of the toolbar.

data-disabled

Present when the toolbar is disabled.

Attribute	Description
`data-orientation`	Indicates the orientation of the toolbar.
`data-disabled`	Present when the toolbar is disabled.

Button

A button that can be used as-is or as a trigger for other components. Renders a <button> element.

focusableWhenDisabled

boolean

(default:

true

)

Name: focusableWhenDisabled
Description: When true the item remains focuseable when disabled.
Type: boolean | undefined
Default: true

nativeButton

boolean

(default:

true

)

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean | undefined
Default: true

disabled

boolean

(default:

false

)

Name: disabled
Description: When true the item is disabled.
Type: boolean | undefined
Default: false

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toolbar.Button.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toolbar.Button.State, ) => ReactElement)

data-highlighted

Present when the button is the active item in the toolbar.

data-orientation

Indicates the orientation of the toolbar.

data-disabled

Present when the button is disabled.

data-focusable

Present when the button remains focusable when disabled.

Attribute	Description
`data-highlighted`	Present when the button is the active item in the toolbar.
`data-orientation`	Indicates the orientation of the toolbar.
`data-disabled`	Present when the button is disabled.
`data-focusable`	Present when the button remains focusable when disabled.

Link

A link component. Renders an <a> element.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toolbar.Link.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toolbar.Link.State, ) => ReactElement)

data-highlighted

Present when the link is the active item in the toolbar.

data-orientation

Indicates the orientation of the toolbar.

Attribute	Description
`data-highlighted`	Present when the link is the active item in the toolbar.
`data-orientation`	Indicates the orientation of the toolbar.

Input

A native input element that integrates with Toolbar keyboard navigation. Renders an <input> element.

defaultValue

Union

Name: defaultValue
Type: string | number | string[] | undefined

focusableWhenDisabled

boolean

(default:

true

)

Name: focusableWhenDisabled
Description: When true the item remains focuseable when disabled.
Type: boolean | undefined
Default: true

disabled

boolean

(default:

false

)

Name: disabled
Description: When true the item is disabled.
Type: boolean | undefined
Default: false

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toolbar.Input.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toolbar.Input.State, ) => ReactElement)

data-highlighted

Present when the input is the active item in the toolbar.

data-orientation

Indicates the orientation of the toolbar.

data-disabled

Present when the input is disabled.

data-focusable

Present when the input remains focusable when disabled.

Attribute	Description
`data-highlighted`	Present when the input is the active item in the toolbar.
`data-orientation`	Indicates the orientation of the toolbar.
`data-disabled`	Present when the input is disabled.
`data-focusable`	Present when the input remains focusable when disabled.

Group

Groups several toolbar items or toggles. Renders a <div> element.

disabled

boolean

(default:

false

)

Name: disabled
Description: When true all toolbar items in the group are disabled.
Type: boolean | undefined
Default: false

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toolbar.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toolbar.Root.State, ) => ReactElement)

data-orientation

Indicates the orientation of the toolbar.

data-disabled

Present when the group is disabled.

Attribute	Description
`data-orientation`	Indicates the orientation of the toolbar.
`data-disabled`	Present when the group is disabled.

Separator

A separator element accessible to screen readers. Renders a <div> element.

orientation

Orientation

(default:

'horizontal'

)

Name: orientation
Description: The orientation of the separator.
Type: 'horizontal' | 'vertical' | undefined
Default: 'horizontal'

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Separator.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Separator.State, ) => ReactElement)

data-orientation

Indicates the orientation of the toolbar.

Attribute	Description
`data-orientation`	Indicates the orientation of the toolbar.

Examples

All Base UI popup components that provide a Trigger component can be integrated with a toolbar by passing the trigger to Toolbar.Button with the render prop:

Using popups with toolbar

return (
  <Toolbar.Root>
    <Menu.Root>
      <Toolbar.Button render={<Menu.Trigger />} />
      <Menu.Portal>
        {/* Compose the rest of the menu */}
      </Menu.Portal>
    </Menu.Root>
  </Toolbar.Root>
)

This applies to AlertDialog, Dialog, Menu, Popover and Select.

Unlike other popups, the toolbar item should be passed to the render prop of Tooltip.Trigger:

Using popups with toolbar

return (
  <Toolbar.Root>
    <Tooltip.Root>
      <Tooltip.Trigger render={<Toolbar.Button />} />
      <Tooltip.Portal>
        {/* Compose the rest of the tooltip */}
      </Tooltip.Portal>
    </Tooltip.Root>
  </Toolbar.Root>
)

Using with NumberField

To use a NumberField in the toolbar, pass NumberField.Input to Toolbar.Input using the render prop:

Using NumberField with toolbar

return (
  <Toolbar.Root>
    <NumberField.Root>
      <NumberField.Group>
        <NumberField.Decrement />
        <Toolbar.Input render={<NumberField.Input />} />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  </Toolbar.Root>
)

Accessibility guidelines

Anatomy

API reference

Root

Button

Link

Input

Group

Separator

Examples

Using with Menu

Using with Tooltip

Using with NumberField