# Toolbar (/cloud/headless/toolbar)



{/* Generated by scripts/sync-base-ui-reference.mjs. Edit the script, not this file. */}

## In Nyte [#in-nyte]

```ts title="Import"
import { Toolbar } from "@nyte-ai/ui/toolbar";
```

`@nyte-ai/ui/toolbar` re-exports the Base UI namespace unchanged. There is no Nyte styling on
this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the
interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

* `desktop/src/renderer/src/workbench/changes-panel.tsx`

The rest of this page is Base UI's documentation for `@base-ui/react/toolbar`, reproduced
verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI
package; in Nyte, import from the subpath above.

## Usage guidelines [#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 [#anatomy]

Import the component and assemble its parts:

```jsx title="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 [#examples]

### Using with Menu [#using-with-menu]

All Base UI popup components that provide a `Trigger` component can be integrated with a toolbar by passing the trigger to `<Toolbar.Button>` with the `render` prop:

```tsx title="Using popups with toolbar"
return (
  <Toolbar.Root>
    <Menu.Root>
      {/* @highlight */}
      <Toolbar.Button render={<Menu.Trigger />} />
      <Menu.Portal>
        {/* prettier-ignore */}
        {/* Compose the rest of the menu */}
      </Menu.Portal>
    </Menu.Root>
  </Toolbar.Root>;
)
```

This applies to `<AlertDialog>`, `<Dialog>`, `<Menu>`, `<Popover>`, and `<Select>`.

### Using with Tooltip [#using-with-tooltip]

Unlike other popups, the toolbar item should be passed to the `render` prop of `<Tooltip.Trigger>`:

```tsx title="Using popups with toolbar"
return (
  <Toolbar.Root>
    <Tooltip.Root>
      {/* @highlight */}
      <Tooltip.Trigger render={<Toolbar.Button />} />
      <Tooltip.Portal>
        {/* prettier-ignore */}
        {/* Compose the rest of the tooltip */}
      </Tooltip.Portal>
    </Tooltip.Root>
  </Toolbar.Root>;
)
```

### Using with NumberField [#using-with-numberfield]

To use a NumberField in the toolbar, pass `<NumberField.Input>` to `<Toolbar.Input>` using the `render` prop:

```tsx title="Using NumberField with toolbar"
return (
  <Toolbar.Root>
    <NumberField.Root>
      <NumberField.Group>
        <NumberField.Decrement />
        {/* @highlight */}
        <Toolbar.Input render={<NumberField.Input />} />
        <NumberField.Increment />
      </NumberField.Group>
    </NumberField.Root>
  </Toolbar.Root>;
)
```

## API reference [#api-reference]

### Root [#root]

A container for grouping a set of controls, such as buttons, toggle groups, or menus.
Renders a `<div>` element.

**Root Props:**

| Prop        | Type                                                                                       | Default        | Description                                                                                                                                                                                   |
| :---------- | :----------------------------------------------------------------------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| loopFocus   | `boolean`                                                                                  | `true`         | If `true`, using keyboard navigation will wrap focus to the other end of the toolbar once the end is reached.                                                                                 |
| disabled    | `boolean`                                                                                  | -              | -                                                                                                                                                                                             |
| orientation | `Toolbar.Root.Orientation`                                                                 | `'horizontal'` | The orientation of the toolbar.                                                                                                                                                               |
| className   | `string \| ((state: Toolbar.Root.State) => string \| undefined)`                           | -              | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style       | `React.CSSProperties \| ((state: Toolbar.Root.State) => React.CSSProperties \| undefined)` | -              | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render      | `ReactElement \| ((props: HTMLProps, state: Toolbar.Root.State) => ReactElement)`          | -              | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Root Data Attributes:**

| Attribute        | Type                         | Description                               |
| :--------------- | :--------------------------- | :---------------------------------------- |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the toolbar. |
| data-disabled    | -                            | Present when the toolbar is disabled.     |

### Root.Props [#rootprops]

Re-export of [Root](#root) props.

### Root.State [#rootstate]

```typescript
type ToolbarRootState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
};
```

### Root.Orientation [#rootorientation]

```typescript
type ToolbarRootOrientation = 'horizontal' | 'vertical';
```

### Root.ItemMetadata [#rootitemmetadata]

```typescript
type ToolbarRootItemMetadata = { disabled: boolean; focusableWhenDisabled: boolean };
```

### Input [#input]

A native input element that integrates with Toolbar keyboard navigation.
Renders an `<input>` element.

**Input Props:**

| Prop                  | Type                                                                                        | Default | Description                                                                                                                                                                                   |
| :-------------------- | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultValue          | `string \| number \| string[]`                                                              | -       | -                                                                                                                                                                                             |
| focusableWhenDisabled | `boolean`                                                                                   | `true`  | When `true` the item remains focusable when disabled.                                                                                                                                         |
| disabled              | `boolean`                                                                                   | `false` | When `true` the item is disabled.                                                                                                                                                             |
| className             | `string \| ((state: Toolbar.Input.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style                 | `React.CSSProperties \| ((state: Toolbar.Input.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render                | `ReactElement \| ((props: HTMLProps, state: Toolbar.Input.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Input Data Attributes:**

| Attribute        | Type                         | Description                                             |
| :--------------- | :--------------------------- | :------------------------------------------------------ |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the toolbar.               |
| data-disabled    | -                            | Present when the input is disabled.                     |
| data-focusable   | -                            | Present when the input remains focusable when disabled. |

### Input.Props [#inputprops]

Re-export of [Input](#input) props.

### Input.State [#inputstate]

```typescript
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 [#group]

Groups several toolbar items or toggles.
Renders a `<div>` element.

**Group Props:**

| Prop      | Type                                                                                        | Default | Description                                                                                                                                                                                   |
| :-------- | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| disabled  | `boolean`                                                                                   | `false` | When `true` all toolbar items in the group are disabled.                                                                                                                                      |
| className | `string \| ((state: Toolbar.Group.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Toolbar.Group.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: HTMLProps, state: Toolbar.Group.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Group Data Attributes:**

| Attribute        | Type                         | Description                               |
| :--------------- | :--------------------------- | :---------------------------------------- |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the toolbar. |
| data-disabled    | -                            | Present when the group is disabled.       |

### Group.Props [#groupprops]

Re-export of [Group](#group) props.

### Group.State [#groupstate]

```typescript
type ToolbarGroupState = {
  /** Whether the component is disabled. */
  disabled: boolean;
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
};
```

### Separator [#separator]

A separator element accessible to screen readers.
Renders a `<div>` element.

**Separator Props:**

| Prop        | Type                                                                                            | Default | Description                                                                                                                                                                                   |
| :---------- | :---------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| orientation | `Orientation`                                                                                   | -       | The orientation of the separator. Defaults to the opposite of the toolbar's&#xA;orientation, so a horizontal toolbar renders vertical separators.                                             |
| className   | `string \| ((state: Toolbar.Separator.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style       | `React.CSSProperties \| ((state: Toolbar.Separator.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render      | `ReactElement \| ((props: HTMLProps, state: Toolbar.Separator.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Separator Data Attributes:**

| Attribute        | Type                         | Description                                                                        |
| :--------------- | :--------------------------- | :--------------------------------------------------------------------------------- |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the separator, which is perpendicular to the toolbar. |

### Separator.Props [#separatorprops]

Re-export of [Separator](#separator) props.

### Separator.State [#separatorstate]

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

### Button [#button]

A button that can be used as-is or as a trigger for other components.
Renders a `<button>` element.

**Button Props:**

| Prop                  | Type                                                                                         | Default | Description                                                                                                                                                                                   |
| :-------------------- | :------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| focusableWhenDisabled | `boolean`                                                                                    | `true`  | When `true` the item remains focusable when disabled.                                                                                                                                         |
| nativeButton          | `boolean`                                                                                    | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).     |
| disabled              | `boolean`                                                                                    | `false` | When `true` the item is disabled.                                                                                                                                                             |
| className             | `string \| ((state: Toolbar.Button.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style                 | `React.CSSProperties \| ((state: Toolbar.Button.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render                | `ReactElement \| ((props: HTMLProps, state: Toolbar.Button.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Button Data Attributes:**

| Attribute        | Type                         | Description                                              |
| :--------------- | :--------------------------- | :------------------------------------------------------- |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the toolbar.                |
| data-disabled    | -                            | Present when the button is disabled.                     |
| data-focusable   | -                            | Present when the button remains focusable when disabled. |

### Button.Props [#buttonprops]

Re-export of [Button](#button) props.

### Button.State [#buttonstate]

```typescript
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 [#link]

A link component.
Renders an `<a>` element.

**Link Props:**

| Prop      | Type                                                                                                                                                              | Default | Description                                                                                                                                                                                   |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Toolbar.Link.State) => string \| undefined)`                                                                                                  | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style     | `React.CSSProperties \| ((state: Toolbar.Link.State) => React.CSSProperties \| undefined)`                                                                        | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render    | `ReactElement \| ((props: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, state: Toolbar.Link.State) => ReactElement)` | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Link Data Attributes:**

| Attribute        | Type                         | Description                               |
| :--------------- | :--------------------------- | :---------------------------------------- |
| data-orientation | `'horizontal' \| 'vertical'` | Indicates the orientation of the toolbar. |

### Link.Props [#linkprops]

Re-export of [Link](#link) props.

### Link.State [#linkstate]

```typescript
type ToolbarLinkState = {
  /** The component orientation. */
  orientation: Toolbar.Root.Orientation;
};
```

## Additional Types [#additional-types]

### Toolbar.Orientation [#toolbarorientation]

```typescript
type ToolbarOrientation = 'horizontal' | 'vertical';
```

## Export Groups [#export-groups]

* `Toolbar.Separator`: `Toolbar.Separator`, `Toolbar.Separator.State`, `Toolbar.Separator.Props`
* `Toolbar.Root`: `Toolbar.Root`, `Toolbar.Root.ItemMetadata`, `Toolbar.Root.Orientation`, `Toolbar.Root.State`, `Toolbar.Root.Props`
* `Toolbar.Group`: `Toolbar.Group`, `Toolbar.Group.State`, `Toolbar.Group.Props`
* `Toolbar.Button`: `Toolbar.Button`, `Toolbar.Button.State`, `Toolbar.Button.Props`
* `Toolbar.Link`: `Toolbar.Link`, `Toolbar.Link.State`, `Toolbar.Link.Props`
* `Toolbar.Input`: `Toolbar.Input`, `Toolbar.Input.State`, `Toolbar.Input.Props`
* `Default`: `Toolbar.Orientation`, `Orientation`, `ToolbarRootItemMetadata`, `ToolbarRootOrientation`, `ToolbarRootState`, `ToolbarRootProps`, `ToolbarGroupState`, `ToolbarGroupProps`, `ToolbarButtonState`, `ToolbarButtonProps`, `ToolbarLinkState`, `ToolbarLinkProps`, `ToolbarInputState`, `ToolbarInputProps`, `ToolbarSeparatorState`, `ToolbarSeparatorProps`

## Canonical Types [#canonical-types]

Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.

* `Toolbar.Separator.State`: `ToolbarSeparatorState`
* `Toolbar.Separator.Props`: `ToolbarSeparatorProps`
* `Toolbar.Root.ItemMetadata`: `ToolbarRootItemMetadata`
* `Toolbar.Root.Orientation`: `ToolbarRootOrientation`
* `Toolbar.Root.State`: `ToolbarRootState`
* `Toolbar.Root.Props`: `ToolbarRootProps`
* `Toolbar.Group.State`: `ToolbarGroupState`
* `Toolbar.Group.Props`: `ToolbarGroupProps`
* `Toolbar.Button.State`: `ToolbarButtonState`
* `Toolbar.Button.Props`: `ToolbarButtonProps`
* `Toolbar.Link.State`: `ToolbarLinkState`
* `Toolbar.Link.Props`: `ToolbarLinkProps`
* `Toolbar.Input.State`: `ToolbarInputState`
* `Toolbar.Input.Props`: `ToolbarInputProps`