Toolbar and actions

Toolbar Shell

Use <nat-table-toolbar> for generic command rows near a table. Projected controls that participate in toolbar keyboard navigation must use natToolbarItem or NatToolbarGroup.

Keep DOM order aligned with screen-reader and roving-keyboard order. Visual placement should not make keyboard navigation surprising.

Table Actions

A Table Action is a user-triggered operation that acts on table rows or table presentation state. Toolbar placement is optional; the behavior is not defined by where the control is rendered.

Wrapper Controls

natToolbarItem puts the roving tabindex on the element it sits on. When that element is a wrapper that renders its real control inside itself — a design-system component, a Stencil custom element — the toolbar forwards focus to the first focusable descendant instead, searching an open shadow root before light DOM. Nothing extra is needed for the common case:

<nat-table-toolbar accessibleName="Table actions">
  <my-button natToolbarItem="archive">Archive</my-button>
</nat-table-toolbar>

The resolved control is taken out of the sequential tab order, keeping the toolbar to a single Tab stop, and is re-suppressed when the wrapper re-renders. This works whether or not the element delegates focus, but delegatesFocus (Stencil shadow: { delegatesFocus: true }) gives the cleanest result: without it, Shift+Tab from the inner control pauses on the wrapper shell for one step before leaving the toolbar, because the shell precedes its own shadow content in sequential order. A native interactive element (<button>, <input>, …) carrying natToolbarItem is always its own target — nothing inside it is ever nominated.

When the default picks the wrong control — a wrapper that renders several, or whose first focusable element is not the primary one — nominate it with natToolbarItemFocusTarget, a CSS selector resolved the same way:

<my-split-button natToolbarItem="archive" natToolbarItemFocusTarget=".primary">Archive</my-split-button>

A control behind a closed shadow root cannot be reached either way — the component must be authored with an open root (Stencil: shadow: true, or delegatesFocus: true), or the toolbar opted out as described below. In development the toolbar warns once per item when it detects a sealed wrapper.

Registration and hit-testing stay on the wrapper, so click, focus and keyboard routing continue to resolve the item normally.

Sealed Controls Without Focus Management

When every projected control is sealed — third-party custom elements with a closed shadow root that you cannot author — the roving pattern has nothing it can manage. In that case opt the whole toolbar out with focusManagement="none":

<nat-table-toolbar accessibleName="Table actions" focusManagement="none">
  <their-button>Archive</their-button>
  <their-button>Export</their-button>
</nat-table-toolbar>

The toolbar then sets no tabindex anywhere: every control keeps its native Tab stop, arrow keys stay with the controls, and the empty-toolbar fallback tab stop on the container is removed. The role="toolbar" landmark and accessible name are kept. This trades away the single-Tab-stop arrow-key navigation of the default mode, so use it only when controls genuinely cannot register — do not combine it with natToolbarItem/NatToolbarGroup markers (a dev-mode warning fires if you do).

Keyboard Order

Toolbar items use roving focus. Put controls in the order users should encounter them, then use toolbar positions for visual grouping. Do not place standalone composite controls inside the toolbar unless their individual interactive elements register correctly.

Text Inputs In The Toolbar

A text field such as a search box keeps Left/Right for moving its own caret through the text. Once the caret reaches the edge of the value, pressing the same arrow again advances roving focus to the adjacent toolbar item, so the field is not a dead-end for arrow navigation. Tab still leaves the field and the toolbar entirely (Shift+Tab steps back out the other side). Multi-value inputs such as number or date pickers keep all their arrow keys, so use Tab to leave those.

Common Uses

Good toolbar content includes refresh buttons, export buttons, column visibility controls, pagination controls, and app-owned bulk actions. Product-specific search and domain filters can sit in or near the toolbar when they fit the workflow.