TabMenu is a TabsList plus TabsTrigger strip for in-page selection that does not change the URL and does not wire TabsContent panels. Operators use it to filter a list, switch a local view mode, or pick a data subset while staying on the same route. The mental model is "a button strip I pick one of"—not "a tab set that swaps linked panels" (that's Tabs) and not "tab-style links" (that's TabNav).
- Filters like All / Active / Completed that re-query the same canvas.
- View modes (list vs. grid, dense vs. comfortable) that keep surrounding context stable.
- Local toggles where opening a new browser tab with Cmd/Ctrl-click is not a required capability.
- Distinct routes that operators should bookmark or share—use
TabNav.
- Regions that hide and show ARIA-controlled panels on the same page—use
Tabs with TabsContent.
- More than about six options—use
Select, Combobox, or a Menu.
- Short labels (1–3 words). Counts live in the
counter prop, not baked into the label. Localize with formatMessage.
- Parallel grammar across tabs ("All / Active / Completed", not "All / Active / The completed ones").
- Controlled value. Use controlled state when syncing to filters or analytics within the same route. Don't sync to the URL here—if the state is shareable, the right component is
TabNav.
- Selection reset. Reset selection when the context object changes (new incident id, new entity in the drawer). Stale selection is a common source of mis-reads.
- Keyboard. Arrow keys move between triggers per the WAI-ARIA tablist pattern.
Do
- Keep tab counts low to avoid horizontal overflow on narrow dispatch layouts.
- Match the visual treatment (underline, small density) to any paired
TabNav in the same surface so operators don't read the two as different systems.
- Provide test ids on triggers for dispatch flows covered by regression tests.
Don't
- Nest another tab strip immediately inside without visible hierarchy. Combine into one strip or introduce a secondary control pattern.
- Use
TabMenu to save vertical space when panels should be linked for accessibility. Upgrade to Tabs.
- Mix TabMenu and TabNav styling so that operators can't tell which one navigates.
TabMenu preserves tablist semantics; selected state is exposed; focus order matches visual order. See Accessibility for the full contract.
