Skip to content

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
horizontal-toolbar.svelte
<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
both-axes-grid.svelte
<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
vertical-menu.svelte
<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

NameTypeDefaultDescription
orientation"both" | "horizontal" | "vertical" | undefined—Arrow key direction for navigation.
itemSelectorstring | undefined—CSS selector for focusable items within the container.
loopboolean | 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

NameTypeDefaultDescription
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.
focusedIndexnumber—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 (disabled or aria-disabled="true") are skipped.
  • Use for toolbars, radio groups, tab lists, and menu navigation patterns.
  • Home and End keys are supported for jumping to first/last items.
  • Call focusItem(index) to programmatically move focus (e.g., after adding/removing items).

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.