API and Development
Toolbar renders a compact role="toolbar" row with one tab stop and arrow-key roving focus. Name it with label (or aria-labelledby) and wrap each control in ToolbarItem. Set floating with toolbarPosition and an optional inset (4, 8 or 16) to place the bar over a positioned ancestor. variant picks the tray: ToolbarVariant.Floating (default) is raised, and ToolbarVariant.Inline is transparent and is the only tray that may be vertical. Separate groups of items with Separator and ToolbarGroup.
| Name | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Toolbar groups, separators, and items. |
aria-description | LocalizedMessage | — | Extended description for assistive tech. |
aria-label | LocalizedMessage | DisplayValue | — | Accessible name when the visible label is insufficient. |
aria-labelledby | string | — | Id of the element that names this toolbar; use {@link ToolbarLabelledByProps} instead. Id of the element that names this toolbar. |
aria-placeholder | LocalizedMessage | — | Hint for an empty control. |
floating | boolean | — | A positioned toolbar is floating; leave it unset to choose an axis. When true, absolutely positions the bar within the nearest positioned ancestor. |
initialItemId | string | — | Item id that receives tabIndex={0} on the first render, including SSR, before items register in effects.
Set this to the id of the first enabled {@link ToolbarItem } when a single tab stop is required in static markup. |
inset | ToolbarInset | — | Inset from positioned edges when floating. Defaults to 4 (--space-4). |
label | LocalizedMessage | — | Accessible name for the toolbar (role="toolbar").
Accessible name prop; use {@link ToolbarLabelProps} instead. |
loop | boolean | — | When true, arrow keys wrap from last item to first and vice versa. |
orientation | ToolbarOrientation | — | Collection axis. Defaults to {@link ToolbarOrientation.Horizontal}. Collection axis. A floating toolbar is always {@link ToolbarOrientation.Horizontal}. |
overflowGlyph | Glyph | — | Glyph for the overflow control. Defaults to more-horizontal. AppShell's compact header uses
more-vertical (TB-16). |
overflowLabel | LocalizedMessage | — | Turns on the overflow menu and names its control (TB-16). When the horizontal toolbar is too narrow for its items,
the trailing items that have an overflowItem move into a menu behind an icon-only "more" control named by this
label, which stays the toolbar's last item. Leave it unset and items never move. A vertical toolbar ignores it. |
overflowMenuOnly | boolean | — | When true, every item with an overflowItem stays in the menu and only the overflow control shows in the bar.
The control stays visible even when the bar is wide enough to show every item (TB-16). |
overflowSize | ButtonSize | — | Size of the overflow control, to match the toolbar's items. Defaults to the Button default. |
ref | Ref<HTMLDivElement> | — | Ref to the rendered toolbar element. |
title | LocalizedMessage | DisplayValue | — | Native tooltip; accessibility hint, not visible UI title text. |
toolbarPosition | ToolbarPosition | — | Placement when floating. Defaults to {@link ToolbarPosition.TopRight}. |
variant | ToolbarVariant | — | Transparent tray with no outer border or shadow. Required to choose a vertical axis.
Surface look for the toolbar tray. Defaults to {@link ToolbarVariant.Floating}, which maps to the shipped overlay
chrome until the floating elevation token syncs (see CONTRACT.md). |
Button with an icon element and a label.
@prepared911/ui, put ToolbarItem outside PopoverTrigger or MenuTrigger, with the Popover or Menu root wrapping both the item and its content. PopoverTrigger and MenuTrigger forward roving props from the item to the control child, so each trigger is one toolbar item with a single tab stop.
overflowLabel (LocalizedMessage) to add a trailing icon-only "more" control (more-horizontal glyph, aria-haspopup="menu"). Optional overflowSize matches the bar's button size. Ignored on a vertical toolbar (development warning; TB-16).
On ToolbarItem, overflowItem is the row in the menu (MenuItem, MenuCheckboxItem, or MenuSub). An item without one stays in the bar, and so do earlier items.