Roving TabIndex
Manages tabindex for keyboard navigation within a group of items. Only the focused item is tabbable; arrow keys move focus between items.
import { createRovingTabIndex } from "phoundry-ui";Horizontal Toolbar
Loading interactive example…
View source
<script lang="ts"> import { createRovingTabIndex } from "phoundry-ui";
let focusedH = $state(0);
const hRoving = createRovingTabIndex({ orientation: "horizontal", loop: true, onFocus: (_el, idx) => (focusedH = idx), });
const toolbarItems = ["Bold", "Italic", "Underline", "Strikethrough", "Code"];</script>
<div class="space-y-3"> <div use:hRoving.action class="flex gap-1" role="toolbar"> {#each toolbarItems as item, i (item)} <button data-roving-item class="rounded px-3 py-1.5 text-xs transition-colors {focusedH === i ? 'bg-accent-primary text-white' : 'bg-surface-raised text-txt-secondary hover:bg-surface-overlay'}" > {item} </button> {/each} </div> <p class="text-[11px] text-txt-tertiary"> Tab into the toolbar, then use <kbd>←</kbd> <kbd>→</kbd> to navigate. Focused: <strong>{toolbarItems[focusedH]}</strong> </p></div>Both axes (grid)
Loading interactive example…
View source
<script lang="ts"> import { createRovingTabIndex } from "phoundry-ui";
let focusedBoth = $state(0);
const bothRoving = createRovingTabIndex({ orientation: "both", loop: false, itemSelector: "[data-roving-item]", onFocus: (_el, idx) => (focusedBoth = idx), });
const gridItems = ["A1", "A2", "B1", "B2"];</script>
<p class="mb-2 text-[11px] text-txt-secondary"> <code>orientation="both"</code> wires ↑↓←→; <code>loop=false</code> stops wrapping at edges - good for spatial palettes.</p><div use:bothRoving.action class="grid w-44 grid-cols-2 gap-1 rounded-lg border border-border-muted p-2" role="group" aria-label="Demo grid"> {#each gridItems as item, i (item)} <button type="button" data-roving-item class="rounded px-2 py-2 text-xs transition-colors {focusedBoth === i ? 'bg-accent-primary text-white' : 'bg-surface-raised text-txt-secondary hover:bg-surface-overlay'}" > {item} </button> {/each}</div><p class="mt-2 text-[11px] text-txt-tertiary"> Focused: {gridItems[focusedBoth]}</p>Vertical Menu
Loading interactive example…
View source
<script lang="ts"> import { createRovingTabIndex } from "phoundry-ui";
let focusedV = $state(0);
const vRoving = createRovingTabIndex({ orientation: "vertical", loop: true, onFocus: (_el, idx) => (focusedV = idx), });
const menuItems = ["Profile", "Settings", "Notifications", "Logout"];</script>
<div class="space-y-3"> <div use:vRoving.action class="flex w-48 flex-col overflow-hidden rounded-lg border border-border-muted" role="menu" > {#each menuItems as item, i (item)} <button role="menuitem" class="px-3 py-2 text-left text-xs transition-colors {focusedV === i ? 'bg-accent-primary/15 text-accent-secondary' : 'text-txt-secondary hover:bg-surface-raised'}" > {item} </button> {/each} </div> <p class="text-[11px] text-txt-tertiary"> Use <kbd>↑</kbd> <kbd>↓</kbd> to navigate. <kbd>Home</kbd> / <kbd>End</kbd> jump to first/last. </p></div>RovingTabIndexOptions
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
orientation | "both" | "horizontal" | "vertical" | undefined | — | Arrow key direction for navigation. |
itemSelector | string | undefined | — | CSS selector for focusable items within the container. |
loop | boolean | undefined | — | Wrap around when reaching the start or end. |
onFocus | ((element: HTMLElement, index: number) => void) | undefined | — | Called when an item receives focus. |
Return Value
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
action | (node: HTMLElement) => { destroy: () => void; } | — | Svelte action to apply to the container element via use:roving.action. |
focusItem | (index: number) => void | — | Programmatically focus a specific item by index. |
focusedIndex | number | — | The currently focused item index. |
Usage tips
- Items are matched by
[role="tab"],[role="menuitem"],[role="option"],[role="treeitem"], or[data-roving-item]by default. - Disabled items (
disabledoraria-disabled="true") are skipped. - Use for toolbars, radio groups, tab lists, and menu navigation patterns.
HomeandEndkeys are supported for jumping to first/last items.- Call
focusItem(index)to programmatically move focus (e.g., after adding/removing items).