{/* Copyright 2023 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:react-aria-components';
import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
import {PropTable, HeaderInfo, TypeLink, PageDescription, ContextTable, StateTable} from '@react-spectrum/docs';
import styles from '@react-spectrum/docs/src/docs.css';
import packageData from 'react-aria-components/package.json';
import Anatomy from '/packages/react-aria/docs/toolbar/toolbar-anatomy.svg';
import ChevronRight from '@spectrum-icons/workflow/ChevronRight';
import {StarterKits} from '@react-spectrum/docs/src/StarterKits';

---
category: Content
keywords: [toolbar, aria]
type: component
---

# Toolbar

<PageDescription>{docs.exports.Toolbar.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['Toolbar']}
  sourceData={[
    {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/'}
  ]} />

## Example

```tsx example
import {Toolbar, Button, ToggleButton, Separator, Checkbox, Group} from 'react-aria-components';

<Toolbar aria-label="Text formatting">
  <Group aria-label="Style">
    <ToggleButton aria-label="Bold"><b>B</b></ToggleButton>
    <ToggleButton aria-label="Italic"><i>I</i></ToggleButton>
    <ToggleButton aria-label="Underline"><u>U</u></ToggleButton>
  </Group>
  <Separator orientation="vertical" />
  <Group aria-label="Clipboard">
    <Button>Copy</Button>
    <Button>Paste</Button>
    <Button>Cut</Button>
  </Group>
  <Separator orientation="vertical" />
  <Checkbox>
    <div className="checkbox">
      <svg viewBox="0 0 18 18" aria-hidden="true">
        <polyline points="1 9 7 14 15 4" />
      </svg>
    </div>
    Night Mode
  </Checkbox>
</Toolbar>
```

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>
```css hidden
@import './Checkbox.mdx' layer(checkbox);
@import './Button.mdx' layer(button);
@import './ToggleButton.mdx' layer(togglebutton);
```

```css
@import "@react-aria/example-theme";

.react-aria-Toolbar {
  display: flex;
  flex-wrap: wrap;
  gap: 5px;

  &[data-orientation=horizontal] {
    flex-direction: row;
  }

  .react-aria-Group {
    display: contents;
  }

  .react-aria-ToggleButton {
    width: 32px;
  }
}

.react-aria-Separator {
  align-self: stretch;
  background-color: var(--border-color);

  &[aria-orientation=vertical] {
    width: 1px;
    margin: 0px 10px;
  }
}
```

</details>

## Features

There is no built-in HTML toolbar element. `Toolbar` helps achieve accessible toolbars with arrow key navigation that can be styled as needed.

* **Flexible** – Support for interactive children such as buttons, checkboxes, dropdown menus, etc. in a horizontal or vertical orientation.
* **Accessible** – Follows the [ARIA toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) with support for arrow key navigation as a single tab stop.

## Anatomy

<Anatomy />

A toolbar consists of a container element for a set of interactive controls. It provides arrow key navigation between its children, in either horizontal or vertical orientation.

```tsx
import {Toolbar} from 'react-aria-components';

<Toolbar>
  {/* ... */}
</Toolbar>
```

## Starter kits

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured [Storybook](https://storybook.js.org/) that you can experiment with, or use as a starting point for your own component library.

<StarterKits component="toolbar" />

## Orientation

By default, toolbars are horizontally oriented. The `orientation` prop can be set to `"vertical"` to change the arrow key navigation behavior.

```tsx example
import Move from '@spectrum-icons/workflow/Move';
import Select from '@spectrum-icons/workflow/Select';
import Polygon from '@spectrum-icons/workflow/PolygonSelect';
import Brush from '@spectrum-icons/workflow/Brush';
import Pencil from '@spectrum-icons/workflow/Edit';

<Toolbar aria-label="Tools" orientation="vertical">
  <Group aria-label="Select">
    <Button aria-label="Move"><Move size="S" /></Button>
    <Button aria-label="Rectangle"><Select size="S" /></Button>
    <Button aria-label="Polygon"><Polygon size="S" /></Button>
  </Group>
  <Separator orientation="horizontal" />
  <Group aria-label="Draw">
    <Button aria-label="Brush"><Brush size="S" /></Button>
    <Button aria-label="Pencil"><Pencil size="S" /></Button>
  </Group>
</Toolbar>
```

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>

```css
.react-aria-Toolbar {
  width: fit-content;

  &[data-orientation=vertical] {
    flex-direction: column;
    align-items: start;
  }
}

.react-aria-Separator {
  &:not([aria-orientation=vertical]) {
    border: none;
    height: 1px;
    width: 100%;
    margin: 10px 0;
  }
}
```

</details>

## Props

### Toolbar

<PropTable component={docs.exports.Toolbar} links={docs.links} />

### Separator

A `<Separator>` can be placed between elements and groups in a toolbar.

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show props</summary>

  <PropTable component={docs.exports.Separator} links={docs.links} />

</details>

## Styling

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin `className` attribute which can be targeted using CSS selectors. These follow the `react-aria-ComponentName` naming convention.

```css
.react-aria-Toolbar {
  /* ... */
}
```

A custom `className` can also be specified on any component. This overrides the default `className` provided by React Aria with your own.

```jsx
<Toolbar className="my-toolbar">
  {/* ... */}
</Toolbar>
```

The `className` and `style` props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like [Tailwind](https://tailwindcss.com/).

```jsx
<Toolbar className={({orientation}) => orientation === 'vertical' ? 'flex-col' : 'flex-row'}>
  {/* ... */}
</Toolbar>
```

The selectors and render props for each component used in a `Toolbar` are documented below.

### Toolbar

A `Toolbar` can be targeted with the `.react-aria-Toolbar` CSS selector, or by overriding with a custom `className`. It supports the following states and render props:

<StateTable properties={docs.exports.ToolbarRenderProps.properties} />

### Separator

A `Separator` can be targeted with the `.react-aria-Separator` CSS selector, or by overriding with a custom `className`.

## Advanced customization

### Contexts

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in [mergeProps](mergeProps.html)).

<ContextTable components={['Toolbar']} docs={docs} />

### Hooks

If you need to customize things further, such as customizing the DOM structure, you can drop down to the lower level Hook-based API. See [useToolbar](useToolbar.html) for more details.
