# Toolbar > A row of buttons, toggles, links, and menus that takes one Tab stop Status: beta. Added in Components 2.16.0. A row of buttons, toggles, links, and menus that takes one Tab stop. ## Import ```tsx import { Toolbar } from '@oztix/roadie-components/toolbar' ``` ## Examples ### Default Each part renders a Roadie component you already know. `Toolbar.Button` is a `Button` at `emphasis='subtler'`, and the toolbar sits in a normal surface, a pill that hugs its items, so a row of buttons reads as one control. ```tsx Undo Redo Save draft ``` ### Sizes `size` sets the buttons and links the toolbar renders, using the `Button` sizes. ```tsx {/* Small */} Undo Redo {/* Medium */} Undo Redo {/* Large */} Undo Redo ``` ### Emphasis `emphasis` sets the surface behind the toolbar: `normal` by default, `subtle`, `raised` or `floating` for a toolbar over other content, and `subtler` for none, when the toolbar sits inside another surface such as a `Card`. The buttons stay at `subtler` on every surface. ```tsx {/* Normal */} Undo Redo {/* Subtle */} Undo Redo {/* Raised */} Undo Redo {/* Floating */} Undo Redo {/* Subtler */} Undo Redo ``` ### States A disabled `Toolbar.Button` stays in the arrow order, so a keyboard user still finds it. `disabled` on `Toolbar.Group`, `Toolbar.ToggleGroup`, or the toolbar disables every item inside it, and they stay in the arrow order too. A `Toolbar.Button` with an `href` takes its own `disabled`, which keeps it in the arrow order and stops the click, but a disabled group or toolbar leaves it active. Disable it too, or remove it, when it shouldn't be followed. ```tsx {/* One button disabled */} Undo Redo {/* Disabled */} Undo Redo ``` ### Composition #### Formatting toolbar `Toolbar.Toggle` is a `Toggle` at the toolbar's size that turns a setting on and off. Toggles in a `Toolbar.ToggleGroup` share one value: give each a `value`, and one is pressed at a time, or several with `multiple`. A `Toolbar.Button` whose only child is an icon renders square, as an `IconButton`, so give it an `aria-label`. Pass `Toolbar.Button` to `Menu.Trigger` with `render` to open a menu. ```tsx Insert} /> }>Image }>Table }>Link ``` Every part takes the toolbar's `size`. Anything passed to `render` keeps its own props instead, so set `size` on it to match. With one value pressed at a time, a `Toolbar.ToggleGroup`'s fill slides from toggle to toggle, as in `ToggleGroup`; with `multiple`, each pressed toggle fills itself. Use it here rather than `ToggleGroup`, whose own track and smaller items wouldn't match the toolbar. #### Links Give `Toolbar.Button` an `href` and it renders a link, as `Button` does: an internal `href` routes through the Link given to `RoadieProvider`, and an external one opens in a new tab. It stays in the arrow order with the buttons. ```tsx Save draft Preview ``` #### Vertical With `orientation='vertical'` the items stack in a column as wide as the widest, and separators run across it. ```tsx ``` #### When space runs out On a touch screen, or a screen narrower than `md`, the items stay on one row and scroll sideways, with the edges fading while there's more to see. Elsewhere they wrap onto new lines, and the pill becomes a rounded box. Arrow keys scroll the focused item into view either way. ```tsx Undo Redo Duplicate Save draft Schedule Preview ``` ## Guidelines - **Group related controls.** Put controls that work together, such as text styles, in a `Toolbar.Group` and separate the groups with `Toolbar.Separator`. - **Drop the surface inside another one.** Inside a `Card`, a pane header, or a bar that already has a surface, use `emphasis='subtler'` so the toolbar doesn't draw a box within a box. Use `floating` for a toolbar over content, such as on an image. - **Keep the toolbar short.** On a phone the row scrolls, so actions past the edge are out of sight until someone scrolls. Put the most used first, and rarely used actions in a `Menu`. - **Size it with `className` or `style`.** Both go on the surface, the toolbar's outermost element. It's at most as wide as its container, so space it with the container's padding or `gap` rather than a margin, which pushes a full-width toolbar past the edge. - **Let its container shrink.** On a phone the toolbar's row is as wide as all its items. A grid or flex item holding it, such as a form control in a `Field`, grows to fit unless it has `min-w-0`. - **Use `Toolbar.Toggle` for an on and off state.** It reports whether it's pressed; a `Toolbar.Button` only runs an action. Put toggles that pick one of a set, such as alignment, in a `Toolbar.ToggleGroup`. - **Wrap popup triggers, not the button.** Pass `Toolbar.Button` to a `Menu.Trigger`, `Popover.Trigger`, or `Tooltip.Trigger` with `render`, so it keeps the toolbar's look and arrow order. - **Label every icon-only control,** and the toolbar itself. ## Accessibility - Renders `role='toolbar'` with `aria-orientation`. Give it an `aria-label`, or point `aria-labelledby` at a visible heading. - **Keyboard:** `Tab` moves into the toolbar and out again in one stop. Arrow keys move between items (`ArrowLeft` and `ArrowRight`, or `ArrowUp` and `ArrowDown` when vertical). Focus wraps from the last item to the first unless `loopFocus` is `false`. - A disabled `Toolbar.Button` keeps focus, with `aria-disabled`, so a screen reader still announces it. - `Toolbar.Separator` renders `role='separator'`, running across the toolbar. ## API reference ### Toolbar ```tsx import { Toolbar } from '@oztix/roadie-components/toolbar' ``` - `disabled`: `boolean`. - `rel`: `string`. Override the auto `rel='noopener noreferrer'` default on external hrefs. - `orientation`: `"horizontal" | "vertical"`. Defaults to `horizontal`. The orientation of the toolbar. - `loopFocus`: `boolean`. Defaults to `true`. If `true`, using keyboard navigation will wrap focus to the other end of the toolbar once the end is reached. - `className`: `string`. Classes for the toolbar's surface, its outermost element. - `size`: `"sm" | "md" | "lg"`. Defaults to `'md'`. The size of the buttons and links the toolbar renders. A `render` element keeps its own size. - `emphasis`: `"normal" | "subtle" | "subtler" | "raised" | "floating"`. Defaults to `'normal'`. The surface behind the toolbar. `subtler` has none, for a toolbar inside another surface. The buttons stay at `subtler` on every one. ### Toolbar.Button - `disabled`: `boolean`. Defaults to `false`. When `true` the item is disabled. - `focusableWhenDisabled`: `boolean`. Defaults to `true`. When `true` the item remains focusable when disabled. - `nativeButton`: `boolean`. Defaults to `true`. Whether the component renders a native `