# 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 stateless: pass `active` and update it in `onClick`, or use `Toolbar.ToggleGroup`
to manage a set of toggles. For a toggle that manages its own state, use [Toggle](https://alpha.mantine.dev/llms/core-toggle.md):

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

`size` prop sets the size of all toggles, padding and gap. Set `orientation="vertical"`
to render a vertical toolbar. `variant` and `color` props change 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" 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 width

By default, toggles are square buttons. Set `autoWidth` prop on `Toolbar.Toggle` or `Toolbar.ToggleItem`
to fit the width to the 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 in 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

Name the toolbar and give each icon-only toggle a label:

```tsx
import { IconBold, IconItalic } from '@tabler/icons-react';
import { Toolbar } from '@mantine/core';

function Demo() {
  return (
    <Toolbar aria-label="Text formatting">
      <Toolbar.ToggleGroup type="multiple">
        <Toolbar.ToggleItem value="bold" aria-label="Bold">
          <IconBold />
        </Toolbar.ToggleItem>
        <Toolbar.ToggleItem value="italic" aria-label="Italic">
          <IconItalic />
        </Toolbar.ToggleItem>
      </Toolbar.ToggleGroup>
    </Toolbar>
  );
}
```

## Keyboard interactions

Toggles share a single tab stop, arrow keys move focus between them.
Other interactive children, for example, `ActionIcon` or `Button`, 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 |
