Skip to main content
Reakit
DocumentationNewsletter
GitHub
GitHub

Toolbar

Accessible Toolbar component that follows the WAI-ARIA Toolbar Pattern. It's a container for grouping a set of controls.

#Installation

npm install reakit

Learn more in Get started.

#Usage

import {
  useToolbarState,
  Toolbar,
  ToolbarItem,
  ToolbarSeparator,
} from "reakit/Toolbar";
import { Button } from "reakit/Button";

function Example() {
  const toolbar = useToolbarState({ loop: true });
  return (
    <Toolbar {...toolbar} aria-label="My toolbar">
      <ToolbarItem {...toolbar} as={Button}>
        Item 1
      </ToolbarItem>
      <ToolbarItem {...toolbar} as={Button}>
        Item 2
      </ToolbarItem>
      <ToolbarSeparator {...toolbar} />
      <ToolbarItem {...toolbar} as={Button}>
        Item 3
      </ToolbarItem>
    </Toolbar>
  );
}

#Toolbar with Menu

You can render Menu within a Toolbar using the same techinique to make a Submenu.

import React from "react";
import { useToolbarState, Toolbar, ToolbarItem } from "reakit/Toolbar";
import { useMenuState, MenuButton, Menu, MenuItem } from "reakit/Menu";
import { Button } from "reakit/Button";

const MoreItems = React.forwardRef((props, ref) => {
  const menu = useMenuState({ placement: "bottom-end" });
  return (
    <>
      <MenuButton {...menu} {...props} ref={ref} aria-label="More items" />
      <Menu {...menu} aria-label="More items">
        <MenuItem {...menu}>Item 3</MenuItem>
        <MenuItem {...menu}>Item 4</MenuItem>
        <MenuItem {...menu}>Item 5</MenuItem>
      </Menu>
    </>
  );
});

function Example() {
  const toolbar = useToolbarState();
  return (
    <Toolbar {...toolbar} aria-label="My toolbar">
      <ToolbarItem {...toolbar} as={Button}>
        Item 1
      </ToolbarItem>
      <ToolbarItem {...toolbar} as={Button}>
        Item 2
      </ToolbarItem>
      <ToolbarItem {...toolbar} as={MoreItems} />
    </Toolbar>
  );
}

#Accessibility

  • Toolbar has role toolbar.
  • Toolbar extends the accessibility features of Composite.
  • ToolbarItem extends the accessibility features of CompositeItem.

Learn more in Accessibility.

#Composition

Learn more in Composition.

#Props

#useToolbarState

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • rtl boolean

    Determines how next and previous functions will behave. If rtl is set to true, they will be inverted. You still need to set dir="rtl" on HTML/CSS.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • loop boolean | "horizontal" | "vertical"

    On one-dimensional composites:

    • true loops from the last item to the first item and vice-versa.
    • horizontal loops only if orientation is horizontal or not set.
    • vertical loops only if orientation is vertical or not set.
    • If currentId is initially set to null, the composite element will be focused in between the last and first items.

    On two-dimensional composites:

    • true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
    • horizontal loops only from the last row item to the first item in the same row.
    • vertical loops only from the last column item to the first item in the column row.
    • If currentId is initially set to null, vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.
    • If wrap matches the value of loop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
  • wrap boolean | "horizontal" | "vertical"

    If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.

    • true wraps between rows and columns.
    • horizontal wraps only between rows.
    • vertical wraps only between columns.
    • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

#Toolbar

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

12 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • wrap boolean | "horizontal" | "vertical"

    If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.

    • true wraps between rows and columns.
    • horizontal wraps only between rows.
    • vertical wraps only between columns.
    • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
  • unstable_moves number

    Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

  • groups Group[]

    Lists all the composite groups with their id and DOM ref. This state is automatically updated when registerGroup and unregisterGroup are called.

  • items Item[]

    Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

  • setCurrentId (value: SetStateAction<string | null | undefine...

    Sets currentId.

  • first () => void

    Moves focus to the first item.

  • last () => void

    Moves focus to the last item.

  • move (id: string | null) => void

    Moves focus to a given item ID.

#ToolbarItem

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

  • id string | undefined

    Same as the HTML attribute.

15 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • unstable_moves number

    Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • items Item[]

    Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

  • setCurrentId (value: SetStateAction<string | null | undefine...

    Sets currentId.

  • first () => void

    Moves focus to the first item.

  • last () => void

    Moves focus to the last item.

  • registerItem (item: Item) => void

    Registers a composite item.

  • unregisterItem (id: string) => void

    Unregisters a composite item.

  • next (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the next item.

  • previous (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the previous item.

  • up (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the item above.

  • down (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the item below.

#ToolbarSeparator

1 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • orientation "horizontal" | "vertical" | undefined

    Separator's orientation.