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>
            <CaretUpDownIcon />
          </Select.Icon>
        </Toolbar.Button>
        <Select.Portal>
          <Select.Positioner
            className={styles.Positioner}
            sideOffset={4}
            alignItemWithTrigger={false}
          >
            <Select.Popup className={styles.Popup}>
              <Select.Item className={styles.Item} value="Helvetica">
                <Select.ItemIndicator className={styles.ItemIndicator}>
                  <CheckIcon />
                </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 />
                </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 CaretUpDownIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      fill="currentColor"
      {...props}
      style={{ display: 'block', ...props.style }}
    >
      <path d="M11 10H5l3 3.5zm0-4H5l3-3.5z" />
    </svg>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      {...props}
      style={{ display: 'block', ...props.style }}
    >
      <path d="m2.5 8.5 4 4 7-9" />
    </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

Using with other components

Use the render prop to combine a toolbar part with a part from another component into a single element. The element joins the toolbar’s keyboard navigation and keeps the behavior of the other part.

Using a menu in a toolbar

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

Popups with a trigger, such as Alert Dialog, Dialog, Drawer, Menu, Popover, and Select: pass the trigger to the render prop of <Toolbar.Button>, as shown above. Set disabled on <Toolbar.Button> rather than on the trigger, so the button stays in the toolbar’s keyboard navigation.
Tooltip: pass <Toolbar.Button> to the render prop of <Tooltip.Trigger> instead.
Number Field: pass <NumberField.Input> to the render prop of <Toolbar.Input>, and keep it inside <NumberField.Root> and <NumberField.Group> with the increment and decrement buttons.

See how props are merged for how the two parts combine.

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 = { disabled: boolean; 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: React.DetailedHTMLProps< React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement >, 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—

Name: orientation
Description: The orientation of the separator. Defaults to the opposite of the toolbar’s orientation, so a horizontal toolbar renders vertical separators.
Type: Orientation | undefined

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 separator, which is perpendicular to the toolbar.

Attribute	Description	-
`data-orientation`	Indicates the orientation of the separator, which is perpendicular to the toolbar.

Toolbar.Separator.PropsHide

Re-Export of Separator props as ToolbarSeparatorProps

Toolbar.Separator.StateHide

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