<ui-toolbar>

A toolbar groups related controls (buttons, links, selects) into a single keyboard-navigable strip using the WAI-ARIA APG Toolbar pattern and roving tabindex. Use <ui-toolbar> when controls belong together conceptually and you want arrow-key navigation within the group; use an ordinary <menu> or a <nav> when the controls are standalone links that don't need arrow-key movement. Source: ui-toolbar.mjs.

Accessibility (WCAG)

• Implements the WAI-ARIA APG Toolbar pattern. role="toolbar" is set on connect (and preserved if the host already carries a different role such as menubar).
• aria-label (or aria-labelledby) is required so the toolbar has an accessible name (WCAG SC 4.1.2 — Name, Role, Value). Every demo on this page provides one.
• Roving tabindex: only the active item carries tabindex="0"; the rest carry tabindex="-1". Tab moves focus into the toolbar at the active item; arrow keys move within (WCAG SC 2.4.3 — Focus Order).
• Arrow keys honour aria-orientation: Left/Right for "horizontal" (default), Up/Down for "vertical". Arrows on the other axis retain their usual behaviour, so e.g. Up/Down still scrolls the page when focus is in a horizontal toolbar (WCAG SC 2.1.1 — Keyboard).
• Home and End jump to the first / last item reachable with the arrows — i.e. the first / last entry of .items, which the next bullet defines.
• Navigation wraps at the boundaries (last → first, first → last). The APG permits either; this component wraps.
• Disabled items support two navigation patterns, selected by their attributes. The APG explicitly permits either excluding disabled items from the roving tabindex or keeping them navigable, so this is a choice the page makes per item rather than a fixed behaviour:
  • disabled — skipped. Excluded from .items, so arrow-key navigation skips it. The control remains visible but cannot receive keyboard focus.
  • aria-disabled="true" — navigable. Kept in .items, so it stays arrow-reachable, focusable and announced as unavailable — and can explain why it is unavailable through its tooltip. It is not activatable: a click on one is stopped by the component, as the APG requires for focusable disabled controls.
  Choose according to whether the user needs to discover the control: keep the item navigable when discovering the disabled functionality matters — when users need to learn that the control exists or how to make it available. Otherwise prefer plain disabled: this keeps keyboard navigation shorter. See §3.
• A hidden item is not navigable, whatever its disabled state. An item carrying hidden, or sitting inside an element that carries it, is left out of .items, so the arrows, Home and End pass over it. This is not a choice the page makes: the browser refuses focus to an element it does not render, so an arrow press onto one would move the roving tabindex and leave focus where it was — the user presses twice to move one place (WCAG SC 2.4.3 — Focus Order). Show the item again and it is back in the arrow order with no further call. It is the attribute that is read, not the used style: ui.css backs hidden with display: none !important, which makes the attribute the one form of hiding a page cannot undo by accident. An item hidden with a class or a media query is still an arrow stop; use the attribute for one that should not be.
• The tab stop never stays on an item that cannot take it. The component writes tabindex over every item matching selector, including the disabled and hidden ones, so a control disabled or hidden while it held the stop is given tabindex="-1" rather than leaving the toolbar with two. Call refresh_tabstop() after that change and the stop moves to the nearest navigable item after it — one place along, not back to the start of the toolbar. A toolbar whose items are all unnavigable still keeps one stop parked, so Tab reaches it as soon as one of them is shown or enabled.
• The navigable form requires aria-disabled — a natively-disabled element cannot be focused at all, by any means, so use the appropriate attribute for the desired behaviour. The same distinction applies to .btn, tooltip() and role="switch", which all use aria-disabled for controls that must remain focusable.

selector defaults to :scope > button, so without it the toolbar manages only its direct <button> children. Nested buttons and links are left alone.

The component sets focus behaviour, not layout. ui.css has no rule for <ui-toolbar>, so it displays inline and its items flow like ordinary text. The demos on this page get their row and column layout from this page's own stylesheet: ui-toolbar { display: flex; gap: var(--size-1); }, plus flex-direction: column for aria-orientation="vertical". Copy that rule when you reuse a demo.