Toolbar · Base UI

A container for grouping a set of buttons and controls.

import * as React from 'react';
import { Toolbar } from '@base-ui/react/toolbar';
import { ToggleGroup } from '@base-ui/react/toggle-group';
import { Toggle } from '@base-ui/react/toggle';
import { Select } from '@base-ui/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 />} 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>
  );
}

Usage 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/react/toolbar';

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

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>;
)

API reference

Root

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

loopFocusbooleantrue

Name: loopFocus
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

disabledboolean—

Name: disabled
Type: boolean | undefined

orientationToolbar.Root.Orientation'horizontal'

Name: orientation
Description: The orientation of the toolbar.
Type: Toolbar.Root.Orientation | undefined
Default: 'horizontal'

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

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.

Toolbar.Root.PropsHide

Re-Export of Root props as ToolbarRootProps

Toolbar.Root.StateHide

type ToolbarRootState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
}

Toolbar.Root.OrientationHide

type ToolbarRootOrientation = 'horizontal' | 'vertical'

Toolbar.Root.ItemMetadataHide

type ToolbarRootItemMetadata = { focusableWhenDisabled: boolean }

Button

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

focusableWhenDisabledbooleantrue

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

nativeButtonbooleantrue

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 (for example, <div>).
Type: boolean | undefined
Default: true

disabledbooleanfalse

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Button.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

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

Toolbar.Button.PropsHide

Re-Export of Button props as ToolbarButtonProps

Toolbar.Button.StateHide

type ToolbarButtonState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** Whether the component remains focusable when disabled. */
  focusable: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
}

Link

A link component. Renders an <a> element.

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Link.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-orientation

Indicates the orientation of the toolbar.

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

Toolbar.Link.PropsHide

Re-Export of Link props as ToolbarLinkProps

Toolbar.Link.StateHide

type ToolbarLinkState = {
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
}

Input

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

defaultValueUnion—

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

focusableWhenDisabledbooleantrue

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

disabledbooleanfalse

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Input.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

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

Toolbar.Input.PropsHide

Re-Export of Input props as ToolbarInputProps

Toolbar.Input.StateHide

type ToolbarInputState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** Whether the component remains focusable when disabled. */
  focusable: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
}

Group

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

disabledbooleanfalse

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

classNamestring | 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.Group.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Group.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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.Group.State, ) => ReactElement) | undefined

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.

Toolbar.Group.PropsHide

Re-Export of Group props as ToolbarGroupProps

Toolbar.Group.StateHide

type ToolbarGroupState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
}

Separator

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

orientationOrientation'horizontal'

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

classNamestring | 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.Separator.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toolbar.Separator.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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.Separator.State, ) => ReactElement) | undefined

data-orientation

Indicates the orientation of the toolbar.

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

Toolbar.Separator.PropsHide

Re-Export of Separator props as ToolbarSeparatorProps

Toolbar.Separator.StateHide

type ToolbarSeparatorState = {
  /** The orientation of the separator. */
  orientation: Orientation;
}

Usage guidelines

Anatomy

Examples

Using with Menu

Using with Tooltip

Using with NumberField

API reference

Root

Toolbar.Root.PropsHide

Toolbar.Root.StateHide

Toolbar.Root.OrientationHide

Toolbar.Root.ItemMetadataHide

Button

Toolbar.Button.PropsHide

Toolbar.Button.StateHide

Link

Toolbar.Link.PropsHide

Toolbar.Link.StateHide

Input

Toolbar.Input.PropsHide

Toolbar.Input.StateHide

Group

Toolbar.Group.PropsHide

Toolbar.Group.StateHide

Separator

Toolbar.Separator.PropsHide

Toolbar.Separator.StateHide