# Toolbar
Package: @mantine/core
Import: import { Toolbar } from '@mantine/core';
Description: Accessible toolbar with toggle groups and roving tabindex keyboard navigation

## Usage

`Toolbar` is a group of toggle buttons with `role="toolbar"` and arrow keys navigation.
`Toolbar.Toggle` is a polymorphic component, it can be rendered as any element, for example
as a link.

`Toolbar.Toggle` is stateless: pass `active` and update it in `onClick`, or use `Toolbar.ToggleGroup`
to manage state of a set of toggles. For a toggle that manages its own state, use the standalone
[Toggle](https://mantine.dev/llms/core-toggle.md) component.

```tsx
import { useState } from 'react';
import {
  LinkSimpleIcon,
  TextAlignCenterIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from '@phosphor-icons/react';
import { Toolbar } from '@mantine/core';

function Demo() {
  const [formatting, setFormatting] = useState<string[]>([]);
  const [alignment, setAlignment] = useState<string | null>('left');

  return (
    <Toolbar>
      <Toolbar.ToggleGroup type="multiple" value={formatting} onChange={setFormatting}>
        <Toolbar.ToggleItem value="bold" aria-label="Bold">
          <TextBIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="italic" aria-label="Italic">
          <TextItalicIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="underline" aria-label="Underline">
          <TextUnderlineIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>

      <Toolbar.Divider />

      <Toolbar.ToggleGroup type="single" value={alignment} onChange={setAlignment}>
        <Toolbar.ToggleItem value="left" aria-label="Align left">
          <TextAlignLeftIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="center" aria-label="Align center">
          <TextAlignCenterIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="right" aria-label="Align right">
          <TextAlignRightIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>

      <Toolbar.Divider />

      <Toolbar.Toggle
        component="a"
        href="https://mantine.dev"
        target="_blank"
        aria-label="Mantine website"
      >
        <LinkSimpleIcon weight="bold" size="100%" />
      </Toolbar.Toggle>
    </Toolbar>
  );
}
```


## Toggle groups

Use `Toolbar.ToggleGroup` with `Toolbar.ToggleItem` to create groups of toggle buttons.
Set `type="single"` to allow one active item at a time or `type="multiple"` to allow several.
With `type="single"`, clicking the active item deselects it and the value becomes `null`.

```tsx
import { useState } from 'react';
import {
  TextAlignCenterIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from '@phosphor-icons/react';
import { Toolbar } from '@mantine/core';

function Demo() {
  const [formatting, setFormatting] = useState<string[]>([]);
  const [alignment, setAlignment] = useState<string | null>('left');

  return (
    <Toolbar>
      <Toolbar.ToggleGroup type="multiple" value={formatting} onChange={setFormatting}>
        <Toolbar.ToggleItem value="bold" aria-label="Bold">
          <TextBIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="italic" aria-label="Italic">
          <TextItalicIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="underline" aria-label="Underline">
          <TextUnderlineIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>

      <Toolbar.Divider />

      <Toolbar.ToggleGroup type="single" value={alignment} onChange={setAlignment}>
        <Toolbar.ToggleItem value="left" aria-label="Align left">
          <TextAlignLeftIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="center" aria-label="Align center">
          <TextAlignCenterIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="right" aria-label="Align right">
          <TextAlignRightIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>
    </Toolbar>
  );
}
```


## Size, orientation, variant and color

The `size` prop controls the size of all toggles, padding and gap.
Set `orientation="vertical"` to render a vertical toolbar. `variant` and `color`
props control the appearance of active toggles.

```tsx
import {
  TextAlignCenterIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from '@phosphor-icons/react';
import { Toolbar } from '@mantine/core';

function Demo() {
  return (
    <Toolbar orientation="horizontal" variant="filled" color="blue" autoContrast={false} size="md" radius="md" withBorder={true}>
      <Toolbar.ToggleGroup type="multiple">
        <Toolbar.ToggleItem value="bold" aria-label="Bold">
          <TextBIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="italic" aria-label="Italic">
          <TextItalicIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="underline" aria-label="Underline">
          <TextUnderlineIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>

      <Toolbar.Divider />

      <Toolbar.ToggleGroup type="single" defaultValue="left">
        <Toolbar.ToggleItem value="left" aria-label="Align left">
          <TextAlignLeftIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="center" aria-label="Align center">
          <TextAlignCenterIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="right" aria-label="Align right">
          <TextAlignRightIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>
    </Toolbar>
  );
}
```


## Auto contrast

Set `autoContrast` prop to automatically adjust icon color based on the active toggle
background color, for example with `variant="filled"` and light colors.

```tsx
import {
  TextAlignCenterIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from '@phosphor-icons/react';
import { Stack, Toolbar } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <Toolbar variant="filled" color="lime.4">
        <Toolbar.ToggleGroup type="multiple" defaultValue={['bold']}>
          <Toolbar.ToggleItem value="bold" aria-label="Bold">
            <TextBIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="italic" aria-label="Italic">
            <TextItalicIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="underline" aria-label="Underline">
            <TextUnderlineIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
        </Toolbar.ToggleGroup>

        <Toolbar.Divider />

        <Toolbar.ToggleGroup type="single" defaultValue="left">
          <Toolbar.ToggleItem value="left" aria-label="Align left">
            <TextAlignLeftIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="center" aria-label="Align center">
            <TextAlignCenterIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="right" aria-label="Align right">
            <TextAlignRightIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
        </Toolbar.ToggleGroup>
      </Toolbar>

      <Toolbar autoContrast variant="filled" color="lime.4">
        <Toolbar.ToggleGroup type="multiple" defaultValue={['bold']}>
          <Toolbar.ToggleItem value="bold" aria-label="Bold">
            <TextBIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="italic" aria-label="Italic">
            <TextItalicIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="underline" aria-label="Underline">
            <TextUnderlineIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
        </Toolbar.ToggleGroup>

        <Toolbar.Divider />

        <Toolbar.ToggleGroup type="single" defaultValue="left">
          <Toolbar.ToggleItem value="left" aria-label="Align left">
            <TextAlignLeftIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="center" aria-label="Align center">
            <TextAlignCenterIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
          <Toolbar.ToggleItem value="right" aria-label="Align right">
            <TextAlignRightIcon weight="bold" size="100%" />
          </Toolbar.ToggleItem>
        </Toolbar.ToggleGroup>
      </Toolbar>
    </Stack>
  );
}
```


## Auto width

By default, `Toolbar.Toggle` and `Toolbar.ToggleItem` render as square buttons. Set `autoWidth`
prop on either of them to allow the toggle width to adjust to its content, for example a text label.

```tsx
import { TextBIcon, TextItalicIcon } from '@phosphor-icons/react';
import { Toolbar } from '@mantine/core';

function Demo() {
  return (
    <Toolbar>
      <Toolbar.Toggle aria-label="Bold">
        <TextBIcon weight="bold" size="100%" />
      </Toolbar.Toggle>
      <Toolbar.Toggle aria-label="Italic">
        <TextItalicIcon weight="bold" size="100%" />
      </Toolbar.Toggle>

      <Toolbar.Divider />

      <Toolbar.Toggle autoWidth>Save</Toolbar.Toggle>
      <Toolbar.Toggle autoWidth>Cancel</Toolbar.Toggle>
    </Toolbar>
  );
}
```


## Disabled state

Set `disabled` prop on individual `Toolbar.ToggleItem` components, or on
`Toolbar.ToggleGroup` to disable all items within the group.

When `Toolbar.Toggle` is rendered as a non-button element (for example, `component="a"`), the `disabled` prop
sets `aria-disabled`, removes the element from the tab order and prevents clicks.

```tsx
import {
  TextAlignCenterIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
  TextBIcon,
  TextItalicIcon,
  TextUnderlineIcon,
} from '@phosphor-icons/react';
import { Toolbar } from '@mantine/core';

function Demo() {
  return (
    <Toolbar>
      <Toolbar.ToggleGroup type="multiple">
        <Toolbar.ToggleItem value="bold" aria-label="Bold">
          <TextBIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="italic" aria-label="Italic" disabled>
          <TextItalicIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="underline" aria-label="Underline">
          <TextUnderlineIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>

      <Toolbar.Divider />

      <Toolbar.ToggleGroup type="single" defaultValue="left" disabled>
        <Toolbar.ToggleItem value="left" aria-label="Align left">
          <TextAlignLeftIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="center" aria-label="Align center">
          <TextAlignCenterIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="right" aria-label="Align right">
          <TextAlignRightIcon weight="bold" size="100%" />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>
    </Toolbar>
  );
}
```


## Accessibility

* `Toolbar` has `role="toolbar"` and `aria-orientation` that matches the `orientation` prop
* `Toolbar.ToggleItem` always has `aria-pressed` attribute. `Toolbar.Toggle` has it only when the `active` prop is passed, without it `Toolbar.Toggle` is a regular button
* Set `aria-label` on icon-only toggles

## Keyboard interactions

`Toolbar.Toggle` and `Toolbar.ToggleItem` components share a single tab stop, arrow keys move focus
between them. Other interactive children (`ActionIcon`, `Button`, standalone `Toggle`) are not part
of the arrow key navigation and remain separate tab stops.


#### Props

**Toolbar props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| autoContrast | boolean | - | Determines whether icon color with filled variant should be changed based on the given `color` prop |
| children | React.ReactNode | required | Toolbar content |
| color | MantineColor | - | Key of `theme.colors` or any valid CSS color, controls color of child toggle components |
| loop | boolean | - | Whether arrow key navigation wraps from last to first item, `true` by default |
| orientation | "horizontal" \| "vertical" | - | Toolbar orientation, `'horizontal'` by default |
| radius | MantineRadius \| number | - | Key of `theme.radius` or any valid CSS value to set `border-radius`, propagated to all children, `theme.defaultRadius` by default |
| size | MantineSize | - | Controls size of toggle components, padding, and gap, `'md'` by default |
| withBorder | boolean | - | Determines whether the toolbar has a border, `true` by default |

**Toolbar.Toggle props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| active | boolean | - | If set, the toggle is displayed in active state |
| autoWidth | boolean | - | If set, the toggle width adjusts to content instead of being square, `false` by default |
| disabled | boolean | - | If set, the toggle is disabled |
| size | string \| number | - | Size passed from parent component, sets `data-size` if value is not number like |

**Toolbar.ToggleGroup props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | required | `Toolbar.ToggleItem` components |
| defaultValue | string \| string[] \| null | - | Uncontrolled default value |
| disabled | boolean | - | Disables all toggle items within this group |
| onChange | (value: string \| null) => void) \| ((value: string[]) => void | - | Called with the new value when an item is toggled, `null` when the active item is deselected Called with the array of active item values when an item is toggled |
| type | "multiple" \| "single" | required | Selection mode: `'single'` allows at most one active item, `'multiple'` allows any number of active items |
| value | string \| string[] \| null | - | Controlled value, `null` when no item is active Controlled value, array of active item values |

**Toolbar.ToggleItem props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| autoWidth | boolean | - | If set, the toggle item width adjusts to content instead of being square, `false` by default |
| disabled | boolean | - | If set, the toggle item is disabled |
| value | string | required | Value used to identify the item in ToggleGroup |


#### Styles API

Toolbar component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Toolbar selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Toolbar-root | Root element |
| group | .mantine-Toolbar-group | `Toolbar.Group` and `Toolbar.ToggleGroup` root element |
| toggle | .mantine-Toolbar-toggle | `Toolbar.Toggle` and `Toolbar.ToggleItem` root element |
| divider | .mantine-Toolbar-divider | `Toolbar.Divider` root element |

**Toolbar CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --toolbar-toggle-size | Controls toggle `height` and `min-width` |
| root | --toolbar-padding | Controls toolbar `padding` |
| root | --toolbar-gap | Controls `gap` between toolbar items |
| root | --toolbar-radius | Controls `border-radius` of toolbar and its children |