Toolbar

Toolbar is a semantic command surface for actions that belong together: document controls, editor tools, filters, view switches, or panel commands. It provides structure around existing Mosmox UI buttons without taking ownership of the business logic.

The component is exported with compound subcomponents: Toolbar.Item, Toolbar.Menu, Toolbar.Group, Toolbar.Separator, and Toolbar.Spacer. Toolbar actions are command buttons, not selectable navigation tabs: clicking an item invokes its handler but does not leave it selected.

InstallationCopy Anchor Link

import { Toolbar, ConfigProvider } from '@mosmox/ui';

Basic usageCopy Anchor Link

<Toolbar aria-label="Document toolbar">
  <Toolbar.Group aria-label="File commands">
    <Toolbar.Item onClick={createDocument}>New</Toolbar.Item>
    <Toolbar.Item onClick={saveDocument}>Save</Toolbar.Item>
  </Toolbar.Group>
  <Toolbar.Separator />
  <Toolbar.Group aria-label="Editing commands">
    <Toolbar.Item onClick={undo}>Undo</Toolbar.Item>
    <Toolbar.Item onClick={redo}>Redo</Toolbar.Item>
  </Toolbar.Group>
  <Toolbar.Spacer />
  <Toolbar.Item onClick={openSettings}>Settings</Toolbar.Item>
</Toolbar>

Toolbar.Item supports the ButtonProps API, including icons, loading state, keyboard shortcuts, and standard button events. It is a command button rather than a link. Toolbar.Group gives related commands their own accessible group, Toolbar.Separator communicates a boundary, and Toolbar.Spacer pushes trailing actions to the opposite edge.

Toolbar itself renders role="toolbar". It can be horizontal or vertical, compact or comfortable, fixed/sticky, full-width, wrapped, disabled as a whole, or displayed as a multi-column/multi-row grid.

Tooltips on toolbar actionsCopy Anchor Link

Add tooltip to any Toolbar.Item or Toolbar.Menu to reuse the standard dark Tooltip on hover and keyboard focus. The optional placement, size, and color can be customized without changing the action itself:

<Toolbar variant="primary" aria-label="Quick actions">
  <Toolbar.Item iconLeft={<Plus />} tooltip="Create a new item">
    Create
  </Toolbar.Item>
  <Toolbar.Item
    aria-label="Search"
    iconLeft={<Search />}
    iconOnly
    tooltip="Search"
    tooltipPlacement="bottom"
    tooltipSize="sm"
  >
    Search
  </Toolbar.Item>
</Toolbar>

The tooltip is shown for both pointer hover and focus, so icon-only actions should still provide an accessible aria-label.

Variants and layout modesCopy Anchor Link

The available variants are surface, bordered, floating, plain, primary, secondary, light, outline, dashed, text, link, danger, and success. The color variants use the same palette as Button. Use orientation="vertical" for a tool rail or command stack, fullWidth to fill its container, and wrap when actions may move onto multiple lines.

Color variants style the Toolbar surface. For example, primary creates a primary-color bar while its commands remain transparent actions inside the bar:

<Toolbar variant="primary" iconOnly aria-label="Primary actions">
  <Toolbar.Item aria-label="Create" iconLeft={<Plus />} />
  <Toolbar.Item aria-label="Settings" iconLeft={<Settings />} />
  <Toolbar.Item aria-label="Search" iconLeft={<Search />} />
</Toolbar>

<Toolbar variant="primary" aria-label="Primary labeled actions">
  <Toolbar.Item iconLeft={<Plus />}>Create</Toolbar.Item>
  <Toolbar.Item iconLeft={<Settings />}>Settings</Toolbar.Item>
</Toolbar>

<Toolbar variant="secondary" aria-label="Secondary actions">
  <Toolbar.Item iconLeft={<Plus />}>Create</Toolbar.Item>
  <Toolbar.Item iconLeft={<Settings />}>Settings</Toolbar.Item>
</Toolbar>

<Toolbar variant="light" aria-label="Light actions">
  <Toolbar.Item iconLeft={<Plus />}>Create</Toolbar.Item>
  <Toolbar.Item iconLeft={<Settings />}>Settings</Toolbar.Item>
</Toolbar>

<Toolbar variant="bordered" fullWidth wrap aria-label="Editor tools">
  <Toolbar.Group aria-label="Formatting">
    <Toolbar.Item onClick={toggleBold}>Bold</Toolbar.Item>
    <Toolbar.Item onClick={toggleItalic}>Italic</Toolbar.Item>
  </Toolbar.Group>
  <Toolbar.Spacer />
  <Toolbar.Item>Share</Toolbar.Item>
</Toolbar>

<Toolbar orientation="vertical" variant="surface" aria-label="Navigation tools">
  <Toolbar.Item onClick={openDashboard}>Dashboard</Toolbar.Item>
  <Toolbar.Item>Reports</Toolbar.Item>
  <Toolbar.Item>Settings</Toolbar.Item>
</Toolbar>

sticky applies sticky positioning to the toolbar so it can remain visible while its content scrolls. The component does not impose a top offset; set one in CSS when it sits below another fixed header.

floating and the floating visual variant are separate concepts: the floating prop changes positioning to fixed, while variant="floating" applies the floating surface styling. They can be used independently or together.

Toolbar menusCopy Anchor Link

Toolbar.Menu is a Toolbar trigger backed by the existing Menu component. It renders a down-arrow trigger and opens the menu below it. Menu entries, selection callbacks, size, variant, width, and max height are passed to Menu.

Menus can also be placed inside a floating, colorized Toolbar:

<Toolbar floating draggable title="Primary menu" initialPosition={{ top: 96, left: 24 }} variant="primary">
  <Toolbar.Menu
    label="Actions"
    entries={[{ key: 'create', label: 'Create', onClick: createItem }]}
  />
</Toolbar>

<Toolbar aria-label="Document actions" variant="bordered">
  <Toolbar.Menu
    label="Insert"
    menuVariant="default"
    entries={[
      { key: 'file', label: 'File', onClick: insertFile },
      { key: 'folder', label: 'Folder', onClick: insertFolder },
    ]}
    onMenuSelect={handleMenuSelect}
  />
  <Toolbar.Menu
    label="View"
    menuSize="sm"
    menuVariant="compact"
    entries={[
      { key: 'preview', label: 'Preview', onClick: openPreview },
      { key: 'details', label: 'Details', onClick: openDetails },
    ]}
  />
</Toolbar>

Floating and draggable toolbarsCopy Anchor Link

Set floating to render the toolbar above the page content with fixed positioning. Add draggable to show a drag handle and let users move it with pointer or touch input. title gives the floating toolbar a named header. initialPosition defines its starting viewport coordinates; both values can be numbers (pixels) or CSS position strings. Dragging starts from the header or empty toolbar area so buttons remain clickable.

Set collapsible to show a chevron that collapses the toolbar to its header. Use defaultCollapsed for an uncontrolled initial state, or collapsed with onCollapsedChange for controlled state.

columns and rows turn the toolbar into a grid. iconOnly passes icon-only behavior to every Toolbar.Item; provide an icon to each item and keep its accessible name with aria-label.

<Toolbar
  aria-label="Quick actions"
  columns={2}
  collapsible
  draggable
  floating
  iconOnly
  initialPosition={{ top: 96, left: 24 }}
  rows={2}
  title="Quick actions"
  variant="floating"
>
  <Toolbar.Item aria-label="Create" iconLeft={<Plus />}>Create</Toolbar.Item>
  <Toolbar.Item aria-label="Save" iconLeft={<Save />}>Save</Toolbar.Item>
  <Toolbar.Item aria-label="Settings" iconLeft={<Settings />}>Settings</Toolbar.Item>
  <Toolbar.Item aria-label="Close" iconLeft={<X />}>Close</Toolbar.Item>
</Toolbar>

When collapsible is enabled, the collapse control is rendered in the floating header. The header is available only for a floating toolbar and is shown when title, draggable, or collapsible is supplied. A controlled toolbar uses collapsed with onCollapsedChange; an uncontrolled toolbar uses defaultCollapsed.

Keyboard and accessibilityCopy Anchor Link

The root renders with role="toolbar" and aria-orientation. Give it an accessible name with aria-label; visible labels can be supplied through a Toolbar.Group label in surrounding UI. With rovingFocus enabled (the default), Left/Right arrows move through horizontal actions, Up/Down arrows move through vertical actions, and Home/End jump to the edges. Disabled actions are skipped.

<Toolbar aria-label="Editor tools" rovingFocus>
  <Toolbar.Item onClick={toggleBold}>Bold</Toolbar.Item>
  <Toolbar.Item>Italic</Toolbar.Item>
  <Toolbar.Item>Underline</Toolbar.Item>
</Toolbar>

Set rovingFocus={false} when a custom keyboard manager owns focus or when every action should remain in the normal tab order.

State, density, and configurationCopy Anchor Link

Toolbar items are command buttons: clicking an item invokes its handler and does not leave the item selected. Set disabled on the toolbar to disable all items, or disable individual items when only one command is unavailable. density accepts compact and comfortable; size accepts default or sm (small).

<ConfigProvider components={{ toolbar: { variant: 'bordered', density: 'compact', size: 'sm' } }}>
  <Toolbar aria-label="Configured toolbar">
    <Toolbar.Item>Configured</Toolbar.Item>
    <Toolbar.Item onClick={runConfiguredCommand}>Provider defaults</Toolbar.Item>
  </Toolbar>
</ConfigProvider>

Instance props override the provider defaults. The toolbar uses shared color, border, shadow, and radius tokens and adapts to the active theme.

API referenceCopy Anchor Link

Toolbar propsCopy Anchor Link

Toolbar.ItemCopy Anchor Link

Supports the Button props; size can override the inherited toolbar size. Toolbar items do not expose a persistent selected state or aria-pressed; use onClick to execute the command. Native button attributes such as type, name, value, form, aria-*, and keyboard/mouse event handlers are also accepted.

Toolbar.MenuCopy Anchor Link

Toolbar.Menu also accepts the standard button and tooltip props supported by Toolbar.Item, including disabled, iconLeft, className, onClick, and tooltip.

The popover is positioned below the trigger. An outside pointer click closes it, and selecting a Menu entry invokes onMenuSelect and closes the popover. Toolbar.Menu controls only the open state of its own menu; the selected value belongs to the supplied Menu entries and application state.

Toolbar.GroupCopy Anchor Link

Toolbar.SeparatorCopy Anchor Link

Toolbar.SpacerCopy Anchor Link

Toolbar.Spacer has no props. It is a decorative flex spacer that pushes following actions to the opposite edge in a horizontal toolbar. In a vertical toolbar it creates flexible vertical space.

ToolbarTooltipPropsCopy Anchor Link

These props are available on Toolbar.Item and Toolbar.Menu:

ConfigProvider APICopy Anchor Link

Toolbar defaults can be configured globally. Instance props override these values:

<ConfigProvider components={{
  toolbar: {
    orientation: 'vertical',
    variant: 'light',
    size: 'sm',
    density: 'compact',
  },
}}>
  <Toolbar aria-label="Tool rail">
    <Toolbar.Item aria-label="Search" iconLeft={<Search />} iconOnly />
    <Toolbar.Item aria-label="Settings" iconLeft={<Settings />} iconOnly />
  </Toolbar>
</ConfigProvider>

All toolbar colors, borders, radius values, shadows, focus states, and typography use the active ConfigProvider theme tokens.