# keyrove

> Keyboard navigation for lists, grids and trees. Configure it with data attributes or JavaScript options, in any framework.

The full text of every page indexed by https://keyrove.pages.dev/llms.txt, in the same order.

---

Source: https://keyrove.pages.dev/docs/introduction

# Introduction

> Add keyboard navigation to lists, grids and trees with one keydown handler, then choose keys and options while native Tab behavior keeps working.

keyrove moves focus through lists, grids and trees. Mark the items you want to
navigate and pass `keydown` events to `keyRove`. It finds and focuses the next
item without rendering UI or wrapping your components.

```html title="Markup"
<ul id="menu">
  <li data-keyrove-item tabindex="0">Inbox</li>
  <li data-keyrove-item tabindex="0">Drafts</li>
  <li data-keyrove-item tabindex="0">Sent</li>
</ul>
```

```ts title="The call"
import { keyRove } from '@mixedrays/keyrove';

const menu = document.querySelector<HTMLElement>('#menu')!;
menu.addEventListener('keydown', (e) => keyRove(e));
```

```ts title="No attributes"
// Keep <li tabindex="0">, but select items without data-keyrove-item.
import { keyRove } from '@mixedrays/keyrove';

const menu = document.querySelector<HTMLElement>('#menu')!;
menu.addEventListener('keydown', (e) => keyRove(e, { items: 'li' }));
```

This list supports arrows, <kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd> and page jumps. <kbd class="kbd">Tab</kbd> still visits each
item. You can [change the keys](#which-keys-move-focus) and configure the group
with [attributes, options, or both](#where-a-group-is-described).

## How it works

1. **Items** are the elements marked with `data-keyrove-item`, read in DOM
   order. An `items` option can select them instead.
2. **The root** is the nearest element at or above the event target marked with
   `data-keyrove-root`, or the listener's element if none is marked. It contains
   the items and carries the group's settings.
3. **The handler**, `keyRove(event)`, reads the key, finds the target item and
   focuses it. It calls `preventDefault()` for handled keys, so navigation does
   not also scroll the page. Unhandled keys keep their browser defaults.

The handler reads the current DOM and settings on every keypress. Changing
items or adding a column count requires no navigation instance to update.

## What it handles

| Feature              | Behavior                                                                                                                                                                                        | Example                                             |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Lists                | <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move one item in DOM order                                                                                                                    | [Basic list](/docs/examples/basic)                  |
| Grids                | <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move a row; <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> move a cell                                                                     | [Grid](/docs/examples/grid)                         |
| First and last items | <kbd class="kbd">Home</kbd>/<kbd class="kbd">End</kbd> jump to list ends or grid row ends; <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Home</kbd>/<kbd class="kbd">End</kbd> jump to grid ends | [Grid](/docs/examples/grid)                         |
| Page jumps           | <kbd class="kbd">PageUp</kbd>/<kbd class="kbd">PageDown</kbd> move 10 items or rows by default                                                                                                  | [Page length](/docs/examples/basic#page-length)     |
| Horizontal lists     | <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> follow the text direction                                                                                                                     | [Horizontal lists](/docs/examples/horizontal-lists) |
| Looping              | Next/previous wrap at list ends                                                                                                                                                                 | [Looping lists](/docs/examples/looping-lists)       |
| Roving tabindex      | One tab stop follows focus within a group                                                                                                                                                       | [Roving tabindex](/docs/examples/roving-tabindex)   |
| Skipped items        | Pass over items marked with `data-keyrove-skip` or `disabled`                                                                                                                                   | [Skipped items](/docs/examples/skipped-items)       |
| Nested groups        | Each group has its own keys, with optional enter and exit bindings                                                                                                                              | [Nested roots](/docs/examples/nested-roots)         |
| Focus shortcuts      | Focus an item or panel from anywhere under the listener                                                                                                                                         | [Focus keys](/docs/examples/focus-keys)             |
| Typeahead            | Add `createTypeahead()` to focus items by typing their labels                                                                                                                                   | [Typeahead](/docs/examples/typeahead)               |
| Trees                | Navigate visible rows; your handlers expand and collapse branches                                                                                                                               | [Tree view](/docs/examples/tree-view)               |
| Moves from code      | Call `rove(list, 'next')` from a button, gamepad or remote                                                                                                                                      | [`rove`](/docs/api#rove-element-action-options)     |

Text fields, selects and editable content keep their editing keys. See
[editable targets](/docs/examples/editable-targets) for the rules and exceptions.

## Where a group is described

Use `data-keyrove-*` attributes in your markup or pass options to the handler.
Options are useful when the HTML comes from a component library or CMS:

```ts
import { keyRove } from '@mixedrays/keyrove';

const config = { items: '[role="menuitem"]', loop: true };
const menu = document.querySelector<HTMLElement>('#share')!;

menu.addEventListener('keydown', (e) => keyRove(e, config));
```

Options override attributes one setting at a time. For example,
`keyRove(e, { loop: true })` enables looping while reading items and key bindings
from the markup.

See [attributes and options](/docs/attributes-and-options) for the full mapping,
or [options in JavaScript](/docs/examples/javascript-options) for a complete demo.

## Which keys move focus

Lists use `ArrowDown` for next and `ArrowUp` for previous by default. Set
`data-keyrove-next-key` and `data-keyrove-prev-key` on the root to use other
`KeyboardEvent.code` values or combinations such as `mod+KeyJ`:

```html
<ul data-keyrove-next-key="KeyJ" data-keyrove-prev-key="KeyK">
  …
</ul>
```

Here, <kbd class="kbd">J</kbd> and <kbd class="kbd">K</kbd> move focus, and the arrows return to their browser defaults.
Each group can have different bindings. <kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd>, <kbd class="kbd">PageUp</kbd> and <kbd class="kbd">PageDown</kbd> can also
be rebound with their own key attributes.

See [custom keys](/docs/examples/custom-keys) for examples and the
[API reference](/docs/api#keys) for defaults, syntax and precedence.

## <kbd class="kbd">Tab</kbd> still works

keyrove uses `element.focus()`, preserving the browser's focus styling,
scrolling and focus announcements. An item also counts as focused when a link,
button or other element inside it has focus.

With the default bindings, <kbd class="kbd">Tab</kbd>, <kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd>, <kbd class="kbd">Enter</kbd>, <kbd class="kbd">Space</kbd> and <kbd class="kbd">Escape</kbd> keep their
usual behavior. Items with `tabindex="0"` remain ordinary tab stops, reachable
with both <kbd class="kbd">Tab</kbd> and the bound navigation keys.

For a single tab stop per group, use
[roving tabindex](/docs/examples/roving-tabindex). <kbd class="kbd">Tab</kbd> enters and leaves the
group, while the bound keys move between its items.

## What it leaves to you

- **Roles and ARIA.** Set the roles, labels and states your widget needs.
  keyrove does not write `role`, `aria-selected` or `aria-activedescendant`.
- **Selection and activation.** Decide what clicks, <kbd class="kbd">Enter</kbd> and <kbd class="kbd">Space</kbd> do, and
  add your own handlers. They are unbound by default.
- **Initial tab stops.** Make items focusable in your markup. For a roving
  group, give one item `tabindex="0"` and the others `-1`, or call
  [`initRovingTabindex`](/docs/api#initrovingtabindex-root-options) after rendering.

The [listbox example](/docs/examples/listbox) combines navigation with all three.

## Framework support

`keyRove` accepts native keyboard events and compatible framework events,
including React's synthetic events. See
[`KeyRoveEvent`](/docs/api#keyroveevent) for the required shape.

[Installation](/docs/installation) shows setup in vanilla JavaScript, React,
Vue and Svelte. Start with the [basic list](/docs/examples/basic) to try it.

---

Source: https://keyrove.pages.dev/docs/installation

# Installation

> Install keyrove from npm and add arrow-key navigation in vanilla JavaScript, React, Vue or Svelte, with typed attribute builders or hand-written attributes.

## Install

```sh title="pnpm"
pnpm add @mixedrays/keyrove
```

```sh title="npm"
npm install @mixedrays/keyrove
```

```sh title="yarn"
yarn add @mixedrays/keyrove
```

The package is ESM-only, ships its own types, and has no runtime dependencies.

## Vanilla

Attach one listener to the container. The container is the navigation root, so
the item query is scoped to it automatically.

```ts
import { keyRove } from '@mixedrays/keyrove';

const list = document.querySelector('#menu');
list.addEventListener('keydown', (e) => keyRove(e));
```

```html
<ul id="menu">
  <li data-keyrove-item tabindex="0">Inbox</li>
  <li data-keyrove-item tabindex="0">Drafts</li>
  <li data-keyrove-item tabindex="0">Sent</li>
</ul>
```

Give non-native items `tabindex="0"` so they can receive focus. With the default
bindings, <kbd class="kbd">Tab</kbd> visits each item. For one tab stop per group, use
[roving tabindex](/docs/examples/roving-tabindex); the
[complete roving setup](#complete-roving-setup) below puts every piece together.

Lists use <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> by default. Set `data-keyrove-next-key` and
`data-keyrove-prev-key` on the root to [change the keys](/docs/examples/custom-keys).
Attribute names are also exported as [constants](/docs/api#constants).

Use options when you cannot add attributes to the markup. For example,
`keyRove(e, { items: '[role="menuitem"]' })` selects items by their role.
See [attributes and options](/docs/attributes-and-options) for the mapping
and fallback rules.

## React

Use [`rootAttributes` and `itemAttributes`](/docs/api#attribute-builders) for
typed settings in markup. They include the root and item markers, and turn
booleans into `"true"` or `"false"`. Hand-written attributes work too.

```tsx title="Typed builders"
import { itemAttributes, keyRove, rootAttributes } from '@mixedrays/keyrove';

export const Menu = ({ items, loop = false }) => (
  <ul {...rootAttributes({ loop })} onKeyDown={keyRove}>
    {items.map((item) => (
      <li key={item.id} {...itemAttributes()} tabIndex={0}>
        {item.label}
      </li>
    ))}
  </ul>
);
```

```tsx title="Hand-written attributes"
import { keyRove } from '@mixedrays/keyrove';

export const Menu = ({ items, loop = false }) => (
  <ul
    data-keyrove-root
    data-keyrove-loop={loop ? 'true' : 'false'}
    onKeyDown={keyRove}
  >
    {items.map((item) => (
      <li key={item.id} data-keyrove-item tabIndex={0}>
        {item.label}
      </li>
    ))}
  </ul>
);
```

React's `SyntheticEvent` satisfies the shape `keyRove` needs, so it can be
passed as the handler directly.

## Vue

```vue title="Typed builders"
<script setup lang="ts">
import { itemAttributes, keyRove, rootAttributes } from '@mixedrays/keyrove';

defineProps<{ items: { id: string; label: string }[]; loop?: boolean }>();
</script>

<template>
  <ul v-bind="rootAttributes({ loop })" @keydown="keyRove">
    <li
      v-for="item in items"
      :key="item.id"
      v-bind="itemAttributes()"
      tabindex="0"
    >
      {{ item.label }}
    </li>
  </ul>
</template>
```

```vue title="Hand-written attributes"
<script setup lang="ts">
import { keyRove } from '@mixedrays/keyrove';

defineProps<{ items: { id: string; label: string }[]; loop?: boolean }>();
</script>

<template>
  <ul
    data-keyrove-root
    :data-keyrove-loop="loop ? 'true' : 'false'"
    @keydown="keyRove"
  >
    <li v-for="item in items" :key="item.id" data-keyrove-item tabindex="0">
      {{ item.label }}
    </li>
  </ul>
</template>
```

## Svelte

```svelte title="Typed builders"
<script lang="ts">
  import { itemAttributes, keyRove, rootAttributes } from '@mixedrays/keyrove';

  let { items, loop = false }: {
    items: { id: string; label: string }[];
    loop?: boolean;
  } = $props();
</script>

<ul {...rootAttributes({ loop })} onkeydown={keyRove}>
  {#each items as item (item.id)}
    <li {...itemAttributes()} tabindex="0">{item.label}</li>
  {/each}
</ul>
```

```svelte title="Hand-written attributes"
<script lang="ts">
  import { keyRove } from '@mixedrays/keyrove';

  let { items, loop = false }: {
    items: { id: string; label: string }[];
    loop?: boolean;
  } = $props();
</script>

<ul
  data-keyrove-root
  data-keyrove-loop={loop ? 'true' : 'false'}
  onkeydown={keyRove}
>
  {#each items as item (item.id)}
    <li data-keyrove-item tabindex="0">{item.label}</li>
  {/each}
</ul>
```

## Several groups, one listener

Mark each group with `data-keyrove-root` to use one listener on a shared
panel or `document`. Each event uses the nearest root at or above its target,
falling back to the listener's element when no root is marked. Sibling roots
keep their items and settings separate.

```html
<div id="panel">
  <ul data-keyrove-root>
    <li data-keyrove-item tabindex="0">Inbox</li>
    <li data-keyrove-item tabindex="0">Drafts</li>
  </ul>

  <!-- A label picker in the same panel: its own root, its own columns. -->
  <ul data-keyrove-root data-keyrove-cols="4">
    <li data-keyrove-item tabindex="0">Work</li>
    <li data-keyrove-item tabindex="0">Travel</li>
  </ul>
</div>
```

```ts
document.querySelector('#panel').addEventListener('keydown', (e) => keyRove(e));
```

Roots can also nest. Each inner group uses its own keys and settings; see
[nested roots](/docs/examples/nested-roots).

## Complete roving setup

A group with one tab stop combines four pieces: navigation, an initial tab
stop, focus tracking and, optionally, typeahead. This recipe wires them to one
configuration object:

```html
<div id="choices">
  <button>Inbox</button>
  <button>Drafts</button>
  <button>Sent</button>
</div>
```

```ts
import {
  createTypeahead,
  followFocus,
  initRovingTabindex,
  keyRove,
} from '@mixedrays/keyrove';

const list = document.querySelector<HTMLElement>('#choices')!;
const config = { items: 'button', rovingTabindex: true };

// Created once, so its buffer lasts between keypresses.
const typeahead = createTypeahead(config);

initRovingTabindex(list, config);

list.addEventListener('keydown', (e) => keyRove(e, config) || typeahead(e));
list.addEventListener('focusin', (e) => followFocus(e, config));
```

- `initRovingTabindex` gives the first button `tabindex="0"` and the others
  `-1`, so <kbd class="kbd">Tab</kbd> enters the group once.
- `keyRove` moves focus with the arrows, <kbd class="kbd">Home</kbd>,
  <kbd class="kbd">End</kbd> and the page keys, and carries the tab stop with
  each move.
- `followFocus` moves the tab stop when focus arrives another way: a click,
  `element.focus()`, or <kbd class="kbd">Tab</kbd> onto a control inside an
  item.
- `typeahead` focuses the first button whose label starts with the typed text.
  Without typeahead, remove `createTypeahead` from the import, the `typeahead`
  line and `|| typeahead(e)`.

Every helper receives the same `config`, so they agree on which elements are
items and that the group has one tab stop.

### After rendering

Call `initRovingTabindex(list, config)` again after a render that may add,
remove or replace items. It keeps a stop that is still valid and repairs a
missing one. The listeners stay attached to `list`, so add them once, outside
the render. In a framework, make the call from the hook that runs after each
render.

### Choosing the first stop

Pass `initial` when your code knows which item should start with the stop,
such as the one your app shows as selected:

```ts
initRovingTabindex(list, {
  ...config,
  initial: list.querySelector('.selected'),
});
```

`initial` overrides the current stop. Use it on first setup or when your app
changes the selection, and leave it out of the post-render call; otherwise
every render sends the stop back and the user loses their place.

This recipe covers focus movement only. Roles, labels and selection belong to
the widget; the [listbox](/docs/examples/listbox) adds them to these pieces.

---

Source: https://keyrove.pages.dev/docs/ai-prompts

# AI prompts

> Copy-ready prompts that point a coding assistant at these docs, from adding keyrove to a project to building a playground.

An assistant may not know keyrove's current API. Each prompt below first
points the assistant at [llms.txt](/llms.txt) and the Markdown version of the
pages it needs, so it works from the current docs.

Paste a prompt into an assistant that can fetch URLs and, for work in an
existing project, read your files. Replace anything in `[brackets]` first. If
the assistant cannot fetch URLs, open the pages the prompt names and paste
them in with **Copy page**, under each page's title.

## Get started

### Add keyrove to your project

The assistant surveys the codebase, proposes where keyrove fits, and waits for
you to choose before it changes anything.

```text copy
I want to add keyboard navigation to this project with keyrove
(@mixedrays/keyrove). Before writing code, read the docs index at
https://keyrove.pages.dev/llms.txt, then
https://keyrove.pages.dev/docs/introduction.md and
https://keyrove.pages.dev/docs/installation.md. Use those pages, not memory,
for API names and behavior.

1. Work out the framework, package manager and component conventions this
   project uses.
2. Find components where arrow-key navigation would help: menus, lists,
   toolbars, tab lists, card grids, trees, sidebars, and any keydown
   handlers that already move focus by hand. List them with file paths and
   the keyrove pattern each would use: list, grid, roving tabindex, nested
   roots or typeahead.
3. Stop and let me pick one before changing anything.
4. For the one I pick, install the package with the project's package
   manager, add the handler and item markers, and keep the existing roles,
   ARIA attributes and click behavior. keyrove only moves focus; roles,
   selection and activation stay with the component.
5. Tell me which keys now work and how to try them.
```

### Build a playground

A throwaway app with one demo per feature and a log of every move. The React
version is a Vite project; the single-file version runs straight from disk
with no install and needs an internet connection to load keyrove from a CDN.

```text title="React" copy
Build me a playground for trying keyrove (@mixedrays/keyrove), a keyboard
navigation library. Read https://keyrove.pages.dev/llms.txt first, then
https://keyrove.pages.dev/docs/installation.md and
https://keyrove.pages.dev/docs/api.md. Use only APIs those pages document.

Make it a Vite + React + TypeScript app: one page, with a section per demo,
each captioned with the keys to press.

- A vertical list with the arrows, Home and End
- A looping list
- A horizontal toolbar
- A grid with a fixed column count, and a CSS grid using cols "auto"
- A list with skipped and disabled items
- A roving-tabindex list with typeahead, using initRovingTabindex,
  followFocus and createTypeahead
- A nested group with enter and exit keys

Add a settings panel for loop, orientation, columns and custom next/prev
keys, applied to the demos with rootAttributes so a change takes effect on
the next keypress. Log every move from onMove (action, from, to) in a panel
at the bottom. Keep the styling plain, with a clearly visible focus ring.

Finish with the commands to install and run it.
```

```text title="One HTML file" copy
Build a single HTML file for trying keyrove (@mixedrays/keyrove), a keyboard
navigation library, with a CDN dependency and no build step.
Read https://keyrove.pages.dev/llms.txt first, then
https://keyrove.pages.dev/docs/introduction.md and
https://keyrove.pages.dev/docs/api.md. Use only APIs those pages document.

Import the package as an ES module from a CDN such as
https://esm.sh/@mixedrays/keyrove, in a <script type="module">. Put one
demo per section, each captioned with the keys to press:

- A vertical list with the arrows, Home and End
- A looping list
- A grid with a fixed column count
- A roving-tabindex list with typeahead
- A nested group with enter and exit keys

Configure the demos with data-keyrove-* attributes, and log every move from
onMove (action, from, to) in a panel at the bottom. Keep the styling plain,
with a clearly visible focus ring.
```

## Build something

### An accessible widget

keyrove moves focus; the widget still needs its roles, states and selection.
This prompt asks for both, following the ARIA pattern for the widget.

```text copy
Build a [listbox | menu | tab list | toolbar | tree view | grid | command
palette] for [what it holds, e.g. "choosing a project"], using keyrove
(@mixedrays/keyrove) for focus movement. Read
https://keyrove.pages.dev/llms.txt first, then
https://keyrove.pages.dev/docs/api.md and the closest example:

- Listboxes and menus: https://keyrove.pages.dev/docs/examples/listbox.md
- Trees: https://keyrove.pages.dev/docs/examples/tree-view.md
- Grids: https://keyrove.pages.dev/docs/examples/grid.md
- Anything with a text field:
  https://keyrove.pages.dev/docs/examples/editable-targets.md

Follow the matching WAI-ARIA Authoring Practices pattern for roles, states
and keys. keyrove does not write roles or aria-* states, and it leaves
selection, expanding and activation to you: add those handlers and chain
them after keyRove with ||, as the listbox example does.

Choose the focus model appropriate to the widget. Use roving tabindex for
groups that move DOM focus between items. A search-based command palette
using the combobox pattern may need focus to stay in the input, with
aria-activedescendant tracking the active result; keyrove does not implement
that model. Explain any behavior keyrove cannot provide.

Write it as [a React component | a Vue component | a Svelte component |
plain HTML and TypeScript] that follows this project's conventions, and list
the keys it supports.
```

### A shared hook or component

Wraps the setup from [complete roving setup](/docs/installation#complete-roving-setup)
once, so every list in a design system gets the same behavior.

```text copy
Wrap keyrove (@mixedrays/keyrove) for this project's design system. Read
https://keyrove.pages.dev/llms.txt, then the "Complete roving setup" section
of https://keyrove.pages.dev/docs/installation.md, and
https://keyrove.pages.dev/docs/api.md.

Create [a React hook | a Vue composable | a Svelte action | a web component]
that sets up a navigable group: keyRove on keydown, optional typeahead, and
optional roving tabindex with initRovingTabindex after each render and
followFocus on focusin. Accept the options keyRove takes and pass them
through unchanged rather than renaming them. Preserve the typeahead handler
across ordinary renders so its buffer survives between keypresses. Ensure
handlers use current options and callbacks without accumulating listeners.
Remove the listeners on unmount.

Then move [component names] onto it, add tests for the arrow keys, Home/End
and the single tab stop, and document it wherever this project documents
shared components.
```

### App-wide shortcuts

Vim-style movement, shortcuts that jump between regions, and keys to step
into and out of a row's controls.

```text copy
Add keyboard shortcuts to [the page or app area] with keyrove
(@mixedrays/keyrove). Read https://keyrove.pages.dev/llms.txt first, then
https://keyrove.pages.dev/docs/examples/custom-keys.md,
https://keyrove.pages.dev/docs/examples/focus-keys.md and
https://keyrove.pages.dev/docs/examples/nested-roots.md.

I want:
- J and K to move through [the main list], alongside the arrows
- [shortcut] to focus [the search field / sidebar / main panel]
- Enter to move into a row's actions, and Escape to move back out
- [anything else]

Before using a binding, check it against browser and screen reader
shortcuts and flag any conflict. Text fields must keep typing normally.
Keep bare-letter shortcuts active only while their component has focus, or
provide a way to disable them or remap them to include Ctrl, Alt or Meta.
Expose each shortcut with aria-keyshortcuts, and list them somewhere users
can find them.
```

## Improve existing code

### Replace hand-written arrow-key code

Finds focus-management code that keyrove could replace and reports the cost of
each swap before touching it.

```text copy
Find the keyboard navigation this codebase implements by hand: keydown
handlers that switch on ArrowUp, ArrowDown, Home or End, focused-index
state, calls to .focus() on siblings, and any roving-tabindex or focus
management libraries. Read https://keyrove.pages.dev/llms.txt,
https://keyrove.pages.dev/docs/introduction.md and
https://keyrove.pages.dev/docs/api.md first.

For each one, tell me whether keyrove (@mixedrays/keyrove) can replace it,
which behavior would change (looping, Home/End, page keys, skipped items,
right-to-left, text fields), and roughly how much code would go. Don't
change anything yet.

When I approve one, replace it. Keep its current keys unless I say
otherwise, and keep or add tests for every key it handled before.
```

### Audit keyboard access

A review with no edits: what a keyboard user meets today, ranked by impact.

```text copy
Audit keyboard access in [this app / the files under src/...]. Read
https://keyrove.pages.dev/llms.txt and
https://keyrove.pages.dev/docs/introduction.md first, so you know what
keyrove (@mixedrays/keyrove) covers and what it leaves to the component.

Go through the composite widgets: menus, listboxes, tabs, toolbars, grids,
trees and lists of cards. For each, report:
- how Tab moves through it now, and whether it should be one tab stop
- the arrow, Home/End and typeahead behavior users would expect
- missing roles, labels or states
- focus that is trapped, invisible, or lost after a delete or re-render

Where browser access is available, exercise the widgets with the keyboard.
Separate reproduced findings from suspected issues, give reproduction steps,
and state what could not be verified.

Rank the findings by impact, with file paths, and mark which ones keyrove
would fix and which need work it does not do. Don't edit any code.
```

### Test keyboard navigation

Tests that press real keys and check where focus lands.

```text copy
Write tests for the keyboard navigation in [component or file]. It uses
keyrove (@mixedrays/keyrove); read https://keyrove.pages.dev/llms.txt and
https://keyrove.pages.dev/docs/api.md for the behavior to expect.

Use the test tools this project already has, such as Testing Library's
user-event or Playwright. Cover:
- each bound key produces the expected movement or no-op, including at
  boundaries
- looping, skipped and disabled items, where the group uses them
- Tab enters and leaves the group, with one tab stop if it roves
- text fields inside the group keep their editing keys
- unbound keys remain unhandled by keyrove, and events an earlier handler
  already prevented cause no navigation
- onMove fires only when focus actually changes, with the expected side
  effects, such as selection that follows focus

Assert on document.activeElement and tabindex attributes, not on internal
state. A grid with cols "auto" reads CSS layout, so test it in a real
browser rather than jsdom.
```

### Debug a group that does not move

Walks the assistant through the usual causes before it changes any code.

```text copy
Keyboard navigation with keyrove (@mixedrays/keyrove) is not working in
[component or file]: [what happens, e.g. "ArrowDown does nothing" or "focus
jumps to the wrong list"]. Read https://keyrove.pages.dev/llms.txt and
https://keyrove.pages.dev/docs/api.md, especially the sections on roots,
precedence, consumed and untouched keys, and editable targets.

Check, in this order:
- the keydown listener is on an element that contains the items
- the items match data-keyrove-item or the items option, and can take focus
- the nearest data-keyrove-root above the target is the intended one
- another handler calls preventDefault first, or a binding overrides the key
- focus is in a text field, select or contenteditable element
- the items are hidden, skipped or disabled

Log keyRove's return value to see whether it consumed the key, and explain
the cause before changing any code.
```

## Writing your own

The prompts above share a few habits worth keeping in your own:

- **Point at the docs.** Start with `https://keyrove.pages.dev/llms.txt` and
  name the pages that matter. Any page's Markdown is at its URL plus `.md`.
- **Say what keyrove leaves out.** Roles, ARIA states, selection and
  activation are the component's job, so ask for them explicitly. See
  [what it leaves to you](/docs/introduction#what-it-leaves-to-you).
- **Ask for a plan first.** For changes across a codebase, have the assistant
  list what it would change and wait for your choice.

---

Source: https://keyrove.pages.dev/docs/attributes-and-options

# Attributes and options

> Configure keyboard navigation with data-keyrove-* attributes, JavaScript options or both, including how options fall back and where the two differ.

Configure a group with `data-keyrove-*` attributes, JavaScript options, or both.
Options override attributes one setting at a time. Some options have different
names or scope; see the [differences below](#configuration-differences).

Here is one group both ways. It is the same list, navigated identically:

```html title="Attributes"
<ul id="menu" data-keyrove-loop>
  <li data-keyrove-item tabindex="0">Inbox</li>
  <li data-keyrove-item tabindex="0">Drafts</li>
</ul>
```

```ts title="Options"
// <ul id="menu"><li tabindex="0">Inbox</li>…</ul>
menu.addEventListener('keydown', (e) =>
  keyRove(e, { items: 'li', loop: true }),
);
```

Choose based on [where you configure the group](#which-to-reach-for).

## They fall back field by field

`keyRove` reads the current settings on every keypress. An omitted option
falls back to its attribute, then to the default:

```ts
keyRove(e); // attributes and defaults
keyRove(e, { loop: true }); // override looping only
keyRove(e, { items: '[role="menuitem"]' }); // override item lookup only
```

`keys` falls back per action. With `{ keys: { next: 'KeyJ' } }`, <kbd class="kbd">J</kbd> moves to
the next item; every other action keeps its attribute or default binding.
An empty, blank or comma-only binding also falls back. Use `'none'` to disable
an action's key.

### Configuration differences

| Setting         | Attributes                                                                                         | Options                                                                                                                                    |
| --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Items           | `data-keyrove-item` marks each item.                                                               | `items` replaces that lookup with a selector or function that returns the items.                                                           |
| Roots           | `data-keyrove-root` marks each root.                                                               | `root` replaces that test with a selector for finding the nearest root. It is not a root element or boolean.                               |
| Roving tabindex | `data-keyrove-roving-tabindex` enables roving on individual items.                                 | `rovingTabindex` is one boolean for the group; `false` overrides item attributes.                                                          |
| Skipping        | `data-keyrove-skip` marks each skipped item.                                                       | `skip` replaces that test with a selector or predicate. Disabled items are always excluded from navigation.                                |
| Move bindings   | Each `data-keyrove-*-key` sets one action's binding.                                               | `keys` overrides bindings per action; omitted or empty entries fall back.                                                                  |
| Focus shortcuts | `data-keyrove-focus-key` is scanned under the listener. Skipped and disabled targets are excluded. | `focusKeys` replaces the whole scan, including when it is `{}`. Explicit targets bypass skip checks, but disabled targets remain excluded. |
| Typeahead label | `data-keyrove-typeahead` sets one item's label.                                                    | `label`, a `createTypeahead` option, is a function over every item. An empty result falls back to the attribute, then the item's text.     |

For example, these two options have different replacement rules:

```ts
keyRove(e, { keys: { next: 'KeyJ' } }); // other actions still fall back
keyRove(e, { focusKeys: { 'ctrl+KeyE': '#editor' } }); // no attribute scan
```

Roving tabindex also differs in scope. The attribute enrolls one item at a
time, so mark every item that shares the tab stop. The option applies to the
whole group:

```html title="Attributes"
<ul id="menu">
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="0">Inbox</li>
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">Drafts</li>
</ul>
```

```ts title="Options"
// <ul id="menu"><li tabindex="0">Inbox</li><li tabindex="-1">Drafts</li></ul>
// Every item shares the stop, whatever its roving attribute says.
menu.addEventListener('keydown', (e) =>
  keyRove(e, { items: 'li', rovingTabindex: true }),
);
```

Either way, [set an initial tab stop](/docs/examples/roving-tabindex#setting-the-initial-tab-stop).

The [API reference](/docs/api#options) lists every option and its fallback.

## Which to reach for

**Use attributes when you write the HTML.** Keep each group's settings beside
its items. One delegated listener can serve [several groups](/docs/installation#several-groups-one-listener)
or [nested roots](/docs/examples/nested-roots).

Use the [attribute builders](/docs/api#attribute-builders) to type-check those
settings in templates. A root configuration can also be passed directly to
`keyRove` without renaming its fields:

```tsx
import { itemAttributes, keyRove, rootAttributes } from '@mixedrays/keyrove';
import type { RootAttributeOptions } from '@mixedrays/keyrove';

const config = {
  loop: true,
  keys: { next: 'KeyJ', prev: 'KeyK' },
} satisfies RootAttributeOptions;

// Settings in markup; the handler reads them on each keypress.
<ul {...rootAttributes(config)} onKeyDown={keyRove}>
  <li {...itemAttributes()} tabIndex={0}>
    Inbox
  </li>
  <li {...itemAttributes()} tabIndex={0}>
    Drafts
  </li>
</ul>;

// The same settings can instead be supplied as options: keyRove(e, config).
```

`rootAttributes` covers columns, looping, orientation, page length and move
bindings, and always marks the root. `itemAttributes` always marks the item;
its `skip`, `rovingTabindex`, `focusKey` and `typeahead` fields describe that
item. The builders emit explicit `"false"` values and omit `undefined` fields.

**Use options when you cannot change the HTML.** Select items by existing roles
or classes in a component library or CMS:

```ts
const config = { items: '[role="menuitem"]', loop: true };

document
  .querySelector('#share')
  .addEventListener('keydown', (e) => keyRove(e, config));
```

**Use options for computed settings.** Build the options object in the handler
to supply a current value on each keypress:

```ts
el.addEventListener('keydown', (e) =>
  keyRove(e, { items: '.cell', cols: columnsNow() }),
);
```

For a CSS grid, `data-keyrove-cols="auto"` or `{ cols: 'auto' }` reads the
column count from the layout; see [responsive grid](/docs/examples/responsive-grid).

## One object, both handlers

`createTypeahead` shares four group options with `keyRove`: `items`, `root`,
`skip` and `rovingTabindex`. Pass the same configuration to both handlers so
they use the same item and skip rules:

```ts
const config = { items: '[role="menuitem"]', loop: true };
const typeahead = createTypeahead(config);

el.addEventListener('keydown', (e) => keyRove(e, config) || typeahead(e));
```

Typeahead uses labels to find items. It has its own `label` option and ignores
movement settings such as keys, columns and looping. Create the handler once
per listener; if its options change, create a new handler. Item queries and
attribute fallbacks still read the current DOM.

[`initRovingTabindex`](/docs/api#initrovingtabindex-root-options) and
[`followFocus`](/docs/api#followfocus-event-options) share the same four group
options. Use them to initialize the tab stop and keep it with focus.

[`rove`](/docs/api#rove-element-action-options) accepts the same options as
`keyRove` and ignores `keys` and `focusKeys`. Pass the same configuration to
move from code: `rove(el, 'next', config)`.

[Options in JavaScript](/docs/examples/javascript-options) shows a complete
menu configured this way.

---

Source: https://keyrove.pages.dev/docs/api

# API reference

> Reference for keyRove, rove, the typeahead and roving tabindex helpers, key bindings, focus behavior, data attributes and every exported TypeScript type.

| Export                                                                   | Purpose                                           |
| ------------------------------------------------------------------------ | ------------------------------------------------- |
| [`keyRove(event, options?)`](#keyrove-event-options)                     | Handles a keydown and reports the focus move.     |
| [`options`](#options)                                                    | Configures the group in JavaScript.               |
| [`rove(element, action, options?)`](#rove-element-action-options)        | Moves focus by action name, without a keypress.   |
| [`createTypeahead(options?)`](#createtypeahead-options)                  | Creates a type-to-focus handler.                  |
| [`matchesCombo(event, combo)`](#matchescombo-event-combo)                | Tests a key combination in your own handlers.     |
| [`initRovingTabindex(root, options?)`](#initrovingtabindex-root-options) | Initializes or repairs a group's roving tab stop. |
| [`followFocus(event, options?)`](#followfocus-event-options)             | Updates the roving tab stop on `focusin`.         |
| [`toggleTabIndex({ root, isActive })`](#toggletabindex-root-isactive)    | Sets one element's `tabindex` to `0` or `-1`.     |
| [`data-keyrove-*`](#attributes)                                          | Configures items and roots in markup.             |
| [`KEYROVE_ATTR_*`](#constants)                                           | Constants for attribute names.                    |
| [Types](#types)                                                          | Event, configuration and result types.            |

## keyRove(event, options?)

Handles one keydown: reads the event's `code`, finds the item the key resolves
to within the event's navigation root, focuses it, and calls `preventDefault()`.

```ts
import { keyRove } from '@mixedrays/keyrove';

list.addEventListener('keydown', (e) => keyRove(e));
```

| Parameter | Type                                | Required | Description                                            |
| --------- | ----------------------------------- | -------- | ------------------------------------------------------ |
| `event`   | [`KeyRoveEvent`](#keyroveevent)     | Yes      | The keydown. Native and framework events both qualify. |
| `options` | [`KeyRoveOptions`](#keyroveoptions) | No       | Group settings and `onMove`; see [options](#options).  |

Returns a [`MoveResult`](#moveaction-moveresult-move), or `null` when the key
is not keyrove's; see [return value](#return-value).

### Keys

Items form a sequence in DOM order. `next` and `prev` move one item. In a
grid, `cols` divides that sequence into rows, and `next-row`/`prev-row` move
one row in the same column. Each move has a `*-key` attribute on the root.

In a list:

| Default key | Bound by                     | Moves                       |
| ----------- | ---------------------------- | --------------------------- |
| `ArrowDown` | `data-keyrove-next-key`      | Next item                   |
| `ArrowUp`   | `data-keyrove-prev-key`      | Previous item               |
| `Home`      | `data-keyrove-home-key`      | First navigable item        |
| `End`       | `data-keyrove-end-key`       | Last navigable item         |
| `PageDown`  | `data-keyrove-page-down-key` | Forward `page-length` items |
| `PageUp`    | `data-keyrove-page-up-key`   | Back `page-length` items    |

In a grid (`data-keyrove-cols` above 1; defaults shown for LTR, the cell arrows
follow the [reading direction](#horizontal-groups-and-rtl)):

| Default key  | Bound by                     | Moves                              |
| ------------ | ---------------------------- | ---------------------------------- |
| `ArrowRight` | `data-keyrove-next-key`      | Next cell, flowing across row ends |
| `ArrowLeft`  | `data-keyrove-prev-key`      | Previous cell                      |
| `ArrowDown`  | `data-keyrove-next-row-key`  | Next row, same column              |
| `ArrowUp`    | `data-keyrove-prev-row-key`  | Previous row, same column          |
| `Home`       | `data-keyrove-home-row-key`  | First navigable cell of the row    |
| `End`        | `data-keyrove-end-row-key`   | Last navigable cell of the row     |
| `ctrl+Home`  | `data-keyrove-home-key`      | First navigable cell of the grid   |
| `ctrl+End`   | `data-keyrove-end-key`       | Last navigable cell of the grid    |
| `PageDown`   | `data-keyrove-page-down-key` | Forward `page-length` rows         |
| `PageUp`     | `data-keyrove-page-up-key`   | Back `page-length` rows            |

Set a move's key attribute to replace its default binding. Set it to `none`
to disable the binding, for example `data-keyrove-page-down-key="none"`.
The replaced key returns to the browser unless another binding handles it.
See [custom keys](/docs/examples/custom-keys).

### Exit and enter

Bind `exit` on an inner root to leave it, or `enter` on the outer root to
focus a group inside the current item. Neither action has a default key.

| Bound by                 | `keys` field | Moves                                                |
| ------------------------ | ------------ | ---------------------------------------------------- |
| `data-keyrove-exit-key`  | `exit`       | From inside a nested root to the group around it     |
| `data-keyrove-enter-key` | `enter`      | From the focused item into the root nested inside it |

```html
<ul data-keyrove-enter-key="Enter">
  <li data-keyrove-item tabindex="0">
    Build failed
    <div data-keyrove-root data-keyrove-exit-key="Escape">
      <button data-keyrove-item tabindex="0">Retry</button>
      <button data-keyrove-item tabindex="0">View logs</button>
    </div>
  </li>
</ul>
```

- **Exit** focuses the containing item in the outer group. If none is eligible,
  it chooses the nearest eligible item after the root, then the nearest before
  it. It never exits beyond the listener's element.
- **Enter** uses the first nested root inside the focused item. It chooses
  that group's first navigable roving item with `tabindex="0"`, or its first
  navigable item. It does not try later roots if the first has no destination.
- Both exclude skipped and disabled items and items belonging to deeper roots.
- Each group keeps its own roving tab stop. A move updates an existing stop in
  the destination group, leaving the source group's stop in place. This lets
  enter return to the item last used in the inner group. Initialize each
  group's stop with [roving tabindex](/docs/examples/roving-tabindex).

When no destination is found, the key remains unhandled. This includes exit
from the listener's own group and enter on an item with no nested root. If a
chosen target cannot receive focus, the key is consumed with `to: null` and
`onMove` does not run, as with other focus moves.

The reported actions are `'exit'` and `'enter'`. See
[nested roots](/docs/examples/nested-roots#getting-back-out) for the demo.

### Combos

Every `*-key` value is a combo, or a list of them, matched by
[`matchesCombo`](#matchescombo-event-combo):

- Zero or more of `mod+`, `ctrl+`, `alt+`, `shift+`, `meta+`, in any order and
  any case, followed by a
  [`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code).
  Whitespace around the parts is ignored.
- `mod` is `meta` on Apple platforms and `ctrl` elsewhere.
- `control`, `option`, `cmd` and `command` are accepted as the longer
  spellings of `ctrl`, `alt` and `meta`.
- The code is the physical key, matched case-sensitively and unaffected by
  keyboard layout: `KeyJ` is the same key on QWERTY and AZERTY. The plus key
  itself is `Equal` or `NumpadAdd`, so `+` is always the separator.
- Matching is exact: every declared modifier must be held, and every undeclared
  one must not be. A bare `KeyJ` matches only while no modifier is held, so
  <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">J</kbd> keeps its browser
  default. A `ctrl+KeyJ` binding never fires on a plain
  <kbd class="kbd">J</kbd>.
- A comma separates the combos of a list, and a move answers to any of them:
  `data-keyrove-next-key="ArrowDown, KeyJ"` keeps the arrow and adds
  <kbd class="kbd">J</kbd>. No code contains a comma (the comma key is
  `Comma`), and whitespace around the commas is ignored. Each entry is matched
  on its own, so an empty entry or one naming an unknown modifier matches
  nothing and leaves the others working. A list is literal like any explicit
  binding: to keep the default key, name it.
- The defaults are exact combos too. A modified
  <kbd class="kbd">PageDown</kbd> is left alone, and so are
  <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Home</kbd> and
  <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">End</kbd> in a list, which has
  no grid-wide scope for them.
- A combo naming an unknown modifier, or ending in a dangling `+`, matches
  nothing, not even a keydown with an empty `code`. An empty or blank value,
  or one of nothing but commas, is unset: an attribute leaves the move its
  default key, and a `keys` value leaves it to the attribute.
- `none`, trimmed and in any case, is not a combo. On its own it binds the move
  to no key; inside a list it is an entry that matches nothing. On a
  [focus key](#focus-keys) it is unset, since an element has no default key to
  free.

### Precedence

One keypress resolves to at most one action. The binding table is searched in
order, and the first match wins:

1. An element's own [focus key](#focus-keys).
2. The root's explicit `*-key` bindings.
3. The defaults of the moves left unbound.

An explicit binding wins over another action's default. For example,
`data-keyrove-next-key="Home"` makes <kbd class="kbd">Home</kbd> move to the next item instead of the
first. Replaced defaults are not restored elsewhere. `none` removes a move's
binding. Bindings for actions the layout does not support, such as row moves
in a list, are ignored.

### Roots

The root is the nearest ancestor of the event target carrying
`data-keyrove-root`, the target itself included, falling back to the element
the listener is attached to (`currentTarget`). A listener on `document` or
`window` falls back to `<html>`.

- The root's attributes configure the group. They are read on every keypress,
  so changing one takes effect at once; see
  [responsive grid](/docs/examples/responsive-grid).
- Items are all enabled `data-keyrove-item` elements under the root, in DOM
  order, except those carrying `disabled`. This includes items in nested
  roots. Use sibling roots to keep attribute-selected sequences separate.
  With [roving tabindex](/docs/examples/roving-tabindex), each root keeps its
  own tab stop: a move onto a nested root's item moves that root's stop and
  leaves the outer group's in place.
- One delegated listener can serve several roots. Inside a
  [nested root](/docs/examples/nested-roots), only that root's movement
  bindings apply; unbound keys do not fall through to the outer group.
  [Focus keys](#focus-keys) can cross root boundaries, and
  [exit and enter](#exit-and-enter) move between a nested root and the group
  around it.
- An item counts as focused when focus is anywhere inside it
  (`:focus-within`), so an item wrapping a link or a button is still the
  position after <kbd class="kbd">Tab</kbd> lands on that inner control.

### Consumed and untouched keys

`preventDefault()` is called for every key keyrove acts on, so the page does
not scroll while you move through a list. What happens to a bound key depends
on where focus is:

- **Focus inside an item of the group.** The key is consumed and focus moves.
  At the end of a list or the edge of a grid there is nowhere to go, and the
  key is still consumed: a group owns its bound keys up to its own boundary.
- **Nothing in the group focused.** Only the moves that can enter a group are
  consumed: the four directional moves, which land on the first navigable item
  (the last, for prev on a looping list), and a [focus key](#focus-keys),
  which lands on its element. <kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd>, the row ends and the page moves act only
  once focus is inside an item; pressed here, they keep their browser default.
- **A group with no items.** Movement keys keep their browser defaults.
  Focus shortcuts can still reach elements that are not items.
- **[Exit and enter](#exit-and-enter).** Unhandled when no destination is found;
  consumed when a target is chosen, even if it cannot receive focus.

Give targets native focusability or a `tabindex`. If a target cannot take
focus, such as a hidden or inert element, the key is consumed without moving.
The roving stop is restored and `onMove` does not fire.

Unbound keys keep their browser behavior and remain available to your
handlers. <kbd class="kbd">Tab</kbd>, <kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd>, <kbd class="kbd">Enter</kbd>, <kbd class="kbd">Space</kbd> and <kbd class="kbd">Escape</kbd> are unbound by default.
The [return value](#return-value) tells your handler whether keyrove consumed
the key. A key another handler already consumed is left alone.

### Edges and looping

At the ends of a list, next and prev are consumed without moving. Add
`data-keyrove-loop` to the root and they wrap instead: forward from the last
navigable item lands on the first, and back from the first lands on the last.
Entering a looping list with prev focuses its last navigable item. Only
next/prev in lists loop; grids keep their boundaries. See
[looping lists](/docs/examples/looping-lists).

A page jump travels as far as it can. One that would overshoot lands on the
last (or first) navigable item rather than doing nothing; in a grid that is the
grid's last (or first) navigable cell, whatever column the jump started in. The
row ends are stricter: `Home` and `End` in a grid look only at the focused
row, so a row of nothing but skipped cells is a consumed no-op.

A skipped item is never a move's destination, including when every item is
skipped. Then no move has anywhere to land. From outside the group, the
directional keys are unhandled and keep their browser default. With focus
already inside an item, such as a skipped item the user clicked, a bound move
is a consumed no-op. Typeahead and roving initialization exclude skipped items
the same way.

### Editable targets

Movement bindings do not run inside editable elements. Those elements keep
their caret, value and typing keys. Editable targets include:

- a `textarea` or a `select`;
- a `[contenteditable]` element and everything inside it, except a
  `contenteditable="false"` island, which opts back out;
- an `input` of any type other than `button`, `checkbox`, `color`, `file`,
  `image`, `reset` and `submit`. On those the bound keys do nothing natively,
  so navigating from them takes nothing away: a list of checkbox rows keeps
  its arrows.

A [focus key](#focus-keys) with <kbd class="kbd">Ctrl</kbd>, <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> can run inside an editable
field. These shortcuts can still conflict with text input: Windows can report
<kbd class="kbd">AltGr</kbd> as <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Alt</kbd>, so a `ctrl+alt+` focus key may fire while typing characters
such as € or @.

When `isComposing` is true, no binding runs, including focus shortcuts. All
keys remain available to the input method.

See [editable targets](/docs/examples/editable-targets) for a demo.

### Horizontal groups and RTL

Reading direction changes the default horizontal arrows. Moves still follow
DOM order. Direction comes from the nearest `dir` attribute; a missing `dir`
or `dir="auto"` falls back to computed style.

- `data-keyrove-orientation="horizontal"` on a list makes `ArrowRight` and
  `ArrowLeft` the next and prev defaults. Under RTL they swap, so a toolbar
  reads "forward" the way its text does. A grid ignores the attribute: its
  cell axis is already horizontal.
- A grid's default cell arrows follow the reading direction the same way. Under
  RTL, DOM order renders right-to-left, so <kbd class="kbd">←</kbd> is the
  next cell; each arrow keeps moving focus the way it points. The row arrows
  never flip.

Both rules apply to defaults only. An explicit binding is literal, never
flipped or remapped, and wins over orientation wherever both are set. The
default arrows it replaces go back to their browser behavior. See
[horizontal lists](/docs/examples/horizontal-lists) for both directions at
work.

### Focus keys

Set `data-keyrove-focus-key="ctrl+shift+KeyE"` on an element to focus it from
anywhere under the listener, including sibling and nested roots. A combo with
<kbd class="kbd">Ctrl</kbd>, <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> also works inside an editable field. Bare codes work outside
editable targets. The reported action is `'focus'`.

- Focus keys sit first in the [binding table](#precedence), so they win any
  collision with the root's bindings or the defaults. Two elements naming one
  combo resolve to the first in DOM order. The attribute scan excludes targets
  with an enabled `data-keyrove-skip` or a `disabled` attribute.
- The element need not be an item. An item stays in its group's order, so the
  arrows reach it too; any other element is reached by its key alone.
- On an item, the move happens in the item's own group: the nearest root above
  it, else the listener's element. An item that is itself a root belongs to
  the group above it. `from` is the item of that group holding focus, or `null`
  when focus was outside it.
- On a non-item destination, `from` is `null` when jumping to it, and no
  roving stop moves. If focus is already inside it, `from` is that element
  and the result is a consumed no-op. Make a panel its inner list's root so
  an arrow after the shortcut enters that list.
- Pressed while focus is already inside its element, the key is a consumed
  no-op: claimed, with `to: null`.
- The element has to be able to take focus. A panel usually needs
  `tabindex="-1"`, which also keeps it out of the
  <kbd class="kbd">Tab</kbd> order. On an element that cannot take focus, the
  key is the same consumed no-op.
- On an item, the roving tab stop moves within the item's group, as for an
  arrow move: when the item focus leaves carries
  `data-keyrove-roving-tabindex`, it drops to `tabindex="-1"` and the target
  takes `0`. When focus leaves an item of a nested group, that group keeps its
  stop, and the target takes its own group's stop. From outside the group
  keyRove leaves the stop where it was, though a
  [`followFocus`](#followfocus-event-options) listener then moves it to the
  item focus landed on.

See [focus keys](/docs/examples/focus-keys) for the pattern at work.

### Options

Use options to configure a group in JavaScript. `keyRove` reads them on each
call, falling back to attributes and defaults for omitted settings. The
options object is typed [`KeyRoveOptions`](#keyroveoptions). See
[configuration differences](/docs/attributes-and-options#configuration-differences)
for naming, scope and replacement rules.

```ts
keyRove(e); // attributes and defaults
keyRove(e, { loop: true }); // override looping only
keyRove(e, { items: '[role="menuitem"]' }); // override item lookup only
```

| Option           | Type                                                                     | Falls back to                  | Meaning                                                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `items`          | `string \| (root: Element) => Element[]`                                 | `data-keyrove-item`            | The group's items: a selector run inside the root, or a function returning them. Elements carrying `disabled` are never navigable.                                             |
| `root`           | `string`                                                                 | `data-keyrove-root`            | Selector a [root](#roots) answers to, matched at or above the event's target.                                                                                                  |
| `cols`           | `number \| 'auto'`                                                       | `data-keyrove-cols`            | Columns. Above 1 the group is a grid. `'auto'` counts the root's CSS grid tracks on every keypress.                                                                            |
| `loop`           | `boolean`                                                                | `data-keyrove-loop`            | Whether next/prev wrap at the ends. Lists only.                                                                                                                                |
| `orientation`    | `'horizontal' \| 'vertical'`                                             | `data-keyrove-orientation`     | `'horizontal'` re-points a list's default arrows; see [RTL](#horizontal-groups-and-rtl).                                                                                       |
| `pageLength`     | `number`                                                                 | `data-keyrove-page-length`     | Rows per page jump — items, in a list.                                                                                                                                         |
| `keys`           | `Partial<Record<StrideAction \| 'exit' \| 'enter', KeyCombo \| 'none'>>` | the `*-key` attributes         | The [combo](#combos) or combos each move answers to: `{ next: 'ArrowDown, KeyJ' }`, or `'none'` for no key. Read move by move. Includes [`exit` and `enter`](#exit-and-enter). |
| `focusKeys`      | `Record<string, string \| Element>`                                      | `data-keyrove-focus-key`       | Combo, or a list of them, → element or a selector resolved within the listener's reach: `{ 'F6, ctrl+KeyE': '#panel' }`. Replaces the attribute scan rather than adding to it. |
| `skip`           | `string \| (element: Element) => boolean`                                | `data-keyrove-skip`            | Which items a move passes over: a selector, or a predicate.                                                                                                                    |
| `rovingTabindex` | `boolean`                                                                | `data-keyrove-roving-tabindex` | Whether the group carries one tab stop. One boolean for the group, where the attribute is read per item.                                                                       |

`keys` falls back per action. `{ keys: { next: 'KeyJ' } }` changes only next;
other actions retain their attribute or default bindings. Empty, blank and
comma-only bindings fall back; `'none'` disables the binding.

A supplied `focusKeys` map, including `{}`, replaces the whole attribute scan.
Its targets bypass skip checks, but disabled targets remain excluded. Selector
targets resolve under the listener; element targets are used directly.

Numeric `cols` and `pageLength` options are rounded down to whole numbers.
Values below 1 or `NaN` fall back to the attribute, then the default if the
attribute is invalid or below 1. Defaults are one column and ten items or rows
per page.

Supply computed values in the call, for example
`keyRove(e, { cols: columnsNow() })`. See
[options in JavaScript](/docs/examples/javascript-options) and the shared
settings accepted by [`createTypeahead`](#createtypeahead-options).

### options.onMove

Fired _after_ focus has moved, and only when it actually moved. A consumed key
with nowhere to go, at the end of a list or the edge of a grid, fires nothing,
and neither does a move whose target does not take focus.

```ts
keyRove(e, {
  onMove: ({ action, from, to }) => console.log(action, from, to),
});
```

`action` is `'next'`, `'prev'`, `'home'`, `'end'`, `'pageUp'` or `'pageDown'`;
`'nextRow'`, `'prevRow'`, `'homeRow'` or `'endRow'` in a grid; `'exit'` or
`'enter'` between nested groups; or `'focus'` for a shortcut. `from` is the item
focus left, or `null` when no item was focused or the destination is a non-item.
`to` is the element that received focus.

### Return value

`keyRove` reports what it did with the key, so handlers compose:

- `null`: the key was not keyrove's and is untouched, browser default included.
  This includes a key another handler already consumed.
- `{ action, from, to }`: the key was consumed. `to` is the newly focused
  element, or `null` for a consumed no-op, where the group owns the key but
  there is nowhere left to go, or the target did not take focus.

A non-null result means the key was consumed. Chain handlers with `||` to
pass only unhandled keys to the next one:

```ts
element.addEventListener('keydown', (e) => keyRove(e) || myOwnHandler(e));
```

The [listbox](/docs/examples/listbox) chains three handlers this way.

A key is already consumed when an earlier handler called `preventDefault()`
on the event. `keyRove` and typeahead return `null` for it without moving
focus, so a component and an app shell can both call keyrove on the same
bubbling event and focus moves once. keyrove never stops propagation, so
ancestor listeners still receive the event. In a `||` chain, `null` still
passes it to your next handler; check `e.defaultPrevented` there if your
handler should skip consumed keys too.

## rove(element, action, options?)

Moves focus by action name, without a keypress. Use it for on-screen next and
previous buttons, gamepads and remotes, or to focus a group's first item with
`rove(list, 'home')`.

```ts
import { rove } from '@mixedrays/keyrove';

nextButton.addEventListener('click', () => rove(results, 'next'));
prevButton.addEventListener('click', () => rove(results, 'prev'));
```

| Parameter | Type                                         | Required | Description                                                          |
| --------- | -------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `element` | `Element \| null \| undefined`               | Yes      | Where to find the group, as described below. Nullish returns `null`. |
| `action`  | [`StrideAction`](#groupoptions-strideaction) | Yes      | The move to make, such as `'next'`, `'home'` or `'nextRow'`.         |
| `options` | [`KeyRoveOptions`](#keyroveoptions)          | No       | The same [options](#options) as `keyRove`; see below.                |

Returns a [`MoveResult`](#moveaction-moveresult-move), or `null` when there is
no move to make.

`action` is a [stride action](#groupoptions-strideaction): `'next'`, `'prev'`,
`'home'`, `'end'`, `'pageUp'` or `'pageDown'`, plus `'nextRow'`, `'prevRow'`,
`'homeRow'` and `'endRow'` in a grid. Key bindings do not affect it. To focus
a specific element, call `element.focus()`, and attach
[`followFocus`](#followfocus-event-options) to a roving group.

The group is found as for a keypress, with `element` as both target and
listener: the nearest [root](#roots) at or above `element`, else `element`
itself.

The move starts from, in this order:

1. The focused item. The move matches its key exactly: same result, roving
   stop and `onMove`.
2. In a roving group, the item holding the tab stop. A button takes focus when
   pressed, so this lets repeated presses continue from the user's position.
3. Otherwise, the move enters the group. `home`, `next`, `nextRow` and
   `pageDown` go to the first navigable item; `end`, `prev`, `prevRow` and
   `pageUp` go to the last. `homeRow` and `endRow` do nothing.

Row actions apply only to grids; in a list they do nothing.

It accepts the same [options](#options) as `keyRove`, including `onMove`, and
ignores `keys` and `focusKeys`.

It returns `{ action, from, to }`, as a keypress does (see
[Return value](#return-value)). `from` is `null` when the move entered the
group. `to` is `null` when there was nowhere to go or the target did not take
focus. It returns `null` when there is no move to make: no group, no item to
enter, or a row action in a list.

## createTypeahead(options?)

Builds a keydown handler that focuses items as their labels are typed.
Printable characters accumulate in a buffer, and focus jumps to the first
navigable item whose label starts with it. Case is ignored, and so are
accents and other combining marks: <kbd class="kbd">E</kbd> reaches _Émilie_,
and <kbd class="kbd">É</kbd> reaches _emilie_.

```ts
import { keyRove, createTypeahead } from '@mixedrays/keyrove';

const typeahead = createTypeahead();

list.addEventListener('keydown', (e) => keyRove(e) || typeahead(e));
```

| Parameter | Type                                                                  | Required | Description                                                     |
| --------- | --------------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `options` | [`TypeaheadOptions`](#typeaheadoptions-typeaheadresult-typeaheadmove) | No       | The typeahead settings below, and the group settings it shares. |

Returns a keydown handler, `(event: KeyRoveEvent) => TypeaheadResult | null`.

Chain it _after_ `keyRove`, as above, so a printable binding like `KeyJ`
navigates instead of entering the buffer. Create one handler per listener: the
buffer lives in the handler, which keeps `keyRove` itself stateless. See
[typeahead](/docs/examples/typeahead) for it at work.

| Option           | Type                            | Default    | Meaning                                                                                                                                  |
| ---------------- | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `label`          | `(item: Element) => string`     | —          | The text an item is matched by. Falls through to the attribute and then the item's text where it returns nothing.                        |
| `resetMs`        | `number`                        | `500`      | Milliseconds of typing silence after which the buffer clears.                                                                            |
| `matchMode`      | `'prefix' \| 'cycle'`           | `'prefix'` | `'cycle'` moves each single-character press to the next matching item after focus, wrapping, so repeats cycle; [see below](#cycle-mode). |
| `foldDiacritics` | `boolean`                       | `true`     | Ignore accents and other combining marks on both sides of the match. Turn it off where an accent tells two items apart.                  |
| `onMove`         | `(move: TypeaheadMove) => void` | —          | Fired after focus has moved, and only then; see [`keyRove`'s option](#options-onmove).                                                   |

It shares `items`, `root`, `skip` and `rovingTabindex` with `keyRove`, using
the same fallback rules. Pass one configuration to both handlers:

```ts
const config = { items: '[role="menuitem"]', loop: true };
const typeahead = createTypeahead(config);

el.addEventListener('keydown', (e) => keyRove(e, config) || typeahead(e));
```

Typeahead ignores movement options: `keys`, `cols`, `loop`, `orientation`
and `pageLength`. Its options are captured when the handler is created;
recreate it to change them. Item queries, skip predicates and attribute
fallbacks still read the current DOM. The
[complete roving setup](/docs/installation#complete-roving-setup) shows it
beside navigation, initialization and focus tracking.

Labels come from `label(item)`, then `data-keyrove-typeahead`, then
`textContent`. An empty value falls through to the next source. Text content
is trimmed and consecutive whitespace is collapsed. Skipped and disabled
items are excluded; a `skip` option replaces the attribute test.
Roots resolve [as in `keyRove`](#roots).

Bindings match the physical `e.code`; typeahead reads `e.key`, the character
the key produced in the user's layout. A press is buffered only when it is
typing:

- a single character, with none of <kbd class="kbd">Ctrl</kbd>,
  <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> held
  (<kbd class="kbd">Shift</kbd> is allowed; it is how capitals are typed);
- not inside an [editable target](#editable-targets);
- a space only once the buffer holds a character, so the spacebar keeps
  scrolling and clicking.

The buffer clears after `resetMs` of silence, and whenever a press resolves to
a different root than the last one, so one delegated handler serves several
groups without carrying a prefix between them. There is no timer to clean up.
A character that matches nothing is left to its browser default but stays in
the buffer, so a mistyped prefix matches nothing more until the reset clears
it.

The handler follows the `keyRove` contract: `null` when the key was left
untouched or [already consumed](#return-value), which leaves the buffer
unchanged, and `{ action: 'typeahead', from, to }` when it was consumed, with
`to: null` when the match is already focused or cannot receive focus.
`onMove` fires after focus has moved and only when it actually moved, so both
handlers can feed the same follow-focus logic. The roving tab stop moves with
the match, as for an arrow move.

### Cycle mode

With `matchMode: 'cycle'`, a buffer holding a single character searches from
the item after the focused one, in DOM order, and wraps past the last item.
Pressing that character again does not grow the buffer, so each press moves on
to the next item starting with it, whether or not the reset has passed in
between. A different character typed before the reset still refines the
prefix, and prefixes longer than one character match from the top as usual.
The trade-off is that a label opening with a doubled letter, such as _Aaron_,
cannot be found by typing "aa".

## matchesCombo(event, combo)

Whether a keydown event matches a [combo](#combos), typed
[`KeyCombo`](#keycombo). This is the matcher behind every key check keyrove
makes, exported for your own handlers.

```ts
import { matchesCombo } from '@mixedrays/keyrove';

list.addEventListener('keydown', (e) => {
  if (matchesCombo(e, 'Escape')) closePanel();
  if (matchesCombo(e, 'mod+KeyK')) openPalette();
});
```

| Parameter | Type                            | Required | Description                                                      |
| --------- | ------------------------------- | -------- | ---------------------------------------------------------------- |
| `event`   | [`KeyRoveEvent`](#keyroveevent) | Yes      | The keydown to test.                                             |
| `combo`   | [`KeyCombo`](#keycombo)         | Yes      | A combo such as `'mod+KeyK'`, or a comma-separated list of them. |

Returns `true` when the event matches the combo, or any combo in the list.

Matching is exact, so `'Escape'` above rejects
<kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Escape</kbd>. A list matches any
of its combos, which saves writing the any-of by hand:

```ts
if (!matchesCombo(e, 'Space, Enter')) return null;
```

## initRovingTabindex(root, options?)

Initializes or repairs a [roving group's](/docs/examples/roving-tabindex) tab
stop. Call it after rendering, and again after a render that may replace items.
`keyRove` does not initialize the stop for you.

```ts
import { initRovingTabindex } from '@mixedrays/keyrove';

initRovingTabindex(list);
```

| Parameter | Type                                                                            | Required | Description                                                                    |
| --------- | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `root`    | `Element \| null \| undefined`                                                  | Yes      | The group's root. Nullish returns `null`.                                      |
| `options` | [`InitRovingTabindexOptions`](#rovingtabindexoptions-initrovingtabindexoptions) | No       | `items`, `root`, `skip` and `rovingTabindex`, plus `initial`, described below. |

Returns the item holding the stop, or `null`.

Only the root's own roving items participate: items marked with
`data-keyrove-roving-tabindex`, or those enabled by the options. Nested roots
keep their own stops; initialize them separately.

The stop is chosen in this order:

1. A valid `initial` item: one of the group's navigable roving items.
2. The first navigable roving item that already has `tabindex="0"`.
3. The first navigable roving item.

Skipped and disabled items cannot hold the stop. All other roving items get
`-1`, including skipped and disabled ones. Only changed attributes are written.

It returns the item holding the stop, or `null` when no roving item is
navigable. Items that do not carry the stop keep whatever `tabindex` they have.

It shares `items`, `root`, `skip` and `rovingTabindex` with the other helpers,
so you can pass the same configuration:

```ts
const config = { items: '[role="menuitem"]', rovingTabindex: true };

initRovingTabindex(menu, config);
menu.addEventListener('keydown', (e) => keyRove(e, config));
```

Use `initial` to choose a stop explicitly, such as a listbox's selected option:

```ts
initRovingTabindex(listbox, {
  initial: listbox.querySelector('[aria-selected="true"]'),
});
```

A valid `initial` overrides the existing stop. Pass it for first setup or an
intentional external selection change. Omit it on routine renders to preserve
the user's position. Null, skipped, disabled or non-roving items are ignored,
using the fallback order above. The
[complete roving setup](/docs/installation#complete-roving-setup) shows where
each call belongs.

## followFocus(event, options?)

Updates a roving group's tab stop when focus enters an item, including clicks,
programmatic focus and <kbd class="kbd">Tab</kbd> entering a control inside an item. Attach it to
`focusin` so returning with <kbd class="kbd">Tab</kbd> reaches the most recently focused item:

```ts
import { followFocus, keyRove } from '@mixedrays/keyrove';

list.addEventListener('keydown', (e) => keyRove(e));
list.addEventListener('focusin', (e) => followFocus(e));
```

| Parameter | Type                                                                        | Required | Description                                   |
| --------- | --------------------------------------------------------------------------- | -------- | --------------------------------------------- |
| `event`   | `Pick<KeyRoveEvent, 'target' \| 'currentTarget'>`                           | Yes      | The `focusin` event.                          |
| `options` | [`RovingTabindexOptions`](#rovingtabindexoptions-initrovingtabindexoptions) | No       | `items`, `root`, `skip` and `rovingTabindex`. |

Returns the item now holding the stop, or `null`.

- The item is found the way a keypress finds its position: the nearest
  [root](#roots) above the target, and the item of its group holding focus.
  Focus on a control inside an item counts as focus on the item.
- Where that root's own items hold no focus, the group around it is asked,
  as far as the listener's element. That covers a panel that is a root and
  also an item of the group around it, and a control of a nested root that
  sits inside an outer item.
- The item takes the stop when it carries one and is not skipped, and every
  other roving item of its group gets `-1`. A nested group's stop is its own
  and is never touched.
- Only attributes that change are written. After one of keyRove's own moves,
  which has already carried the stop, the `focusin` it causes writes nothing.

It returns the item now holding the stop, or `null` when focus is in no item
that carries one. It takes the same [group settings](#options) as
[`initRovingTabindex`](#initrovingtabindex-root-options): `items`, `root`,
`skip` and `rovingTabindex`. See the
[complete roving setup](/docs/installation#complete-roving-setup) for all
the helpers wired together.

## toggleTabIndex({ root, isActive })

Sets `tabindex` to `0` or `-1` on a single element.

```ts
import { toggleTabIndex } from '@mixedrays/keyrove';

toggleTabIndex({ root: firstItem, isActive: true });
```

| Parameter  | Type                           | Required | Description                               |
| ---------- | ------------------------------ | -------- | ----------------------------------------- |
| `root`     | `Element \| null \| undefined` | Yes      | The element to set. Nullish is a no-op.   |
| `isActive` | `boolean`                      | Yes      | `true` sets `tabindex="0"`, `false` `-1`. |

Returns nothing.

Use it where you manage one element's tab stop yourself. For a whole roving
group, [`initRovingTabindex`](#initrovingtabindex-root-options) keeps exactly
one `0` for you, and [`followFocus`](#followfocus-event-options) moves it with
focus that keyRove did not move. Descendant tab stops are left alone; roving tabindex
only needs the item itself to carry the stop. A nullish `root` is a no-op, so a
query that found nothing needs no guard.

## Attributes

The table below describes attribute configuration. The [options table](#options)
maps it to JavaScript; [configuration differences](/docs/attributes-and-options#configuration-differences)
explains scope and replacement exceptions.

On an item:

| Attribute                      | Meaning                                                                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-keyrove-item`            | Marks an element as navigable. It is the position whenever focus is anywhere inside it.                                                                                              |
| `data-keyrove-skip`            | Passed over when moving; keeps its place in the sequence. `disabled` also excludes an element, but removes it from the sequence entirely, so in a grid it shifts the cells after it. |
| `data-keyrove-roving-tabindex` | Moves the `tabindex="0"` tab stop along with focus.                                                                                                                                  |
| `data-keyrove-focus-key`       | [Combo](#combos) that focuses this element from anywhere under the listener, e.g. `ctrl+shift+KeyE`. Works without `data-keyrove-item`, too.                                         |
| `data-keyrove-typeahead`       | Label for [type-to-focus](#createtypeahead-options), when the item's own text is not it.                                                                                             |

On the root, read on every keypress:

| Attribute                    | Default                                                  | Meaning                                                                                                                                                                                                                 |
| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-keyrove-root`          | —                                                        | Marks the root explicitly, instead of the listener's element.                                                                                                                                                           |
| `data-keyrove-cols`          | `1`                                                      | Column count; above 1 the group navigates as a grid. Values below 1 fall back to the default. `auto` counts the tracks of the root's CSS grid on every keypress; see [responsive grid](/docs/examples/responsive-grid). |
| `data-keyrove-page-length`   | `10`                                                     | Items per page jump; rows, in a grid. Values below 1 fall back to the default.                                                                                                                                          |
| `data-keyrove-loop`          | —                                                        | Next and prev wrap past the ends of a list. Grids never wrap. See [looping lists](/docs/examples/looping-lists).                                                                                                        |
| `data-keyrove-orientation`   | —                                                        | `horizontal` re-points a list's next/prev defaults at `ArrowRight`/`ArrowLeft`, RTL-aware. See [horizontal lists](/docs/examples/horizontal-lists).                                                                     |
| `data-keyrove-next-key`      | `ArrowDown`; `ArrowRight` in a horizontal list or a grid | Next item; the next cell, in a grid. E.g. `KeyJ` or `ctrl+ArrowRight`.                                                                                                                                                  |
| `data-keyrove-prev-key`      | `ArrowUp`; `ArrowLeft` in a horizontal list or a grid    | Previous item.                                                                                                                                                                                                          |
| `data-keyrove-next-row-key`  | `ArrowDown`                                              | Next row, same column. Grid only.                                                                                                                                                                                       |
| `data-keyrove-prev-row-key`  | `ArrowUp`                                                | Previous row, same column. Grid only.                                                                                                                                                                                   |
| `data-keyrove-home-key`      | `Home`; `ctrl+Home` in a grid                            | First item; the grid's first cell.                                                                                                                                                                                      |
| `data-keyrove-end-key`       | `End`; `ctrl+End` in a grid                              | Last item; the grid's last cell.                                                                                                                                                                                        |
| `data-keyrove-home-row-key`  | `Home`                                                   | First cell of the focused row. Grid only.                                                                                                                                                                               |
| `data-keyrove-end-row-key`   | `End`                                                    | Last cell of the focused row. Grid only.                                                                                                                                                                                |
| `data-keyrove-page-up-key`   | `PageUp`                                                 | Page jump back.                                                                                                                                                                                                         |
| `data-keyrove-page-down-key` | `PageDown`                                               | Page jump forward.                                                                                                                                                                                                      |
| `data-keyrove-exit-key`      | —                                                        | From inside this nested root to the group around it. See [exit and enter](#exit-and-enter).                                                                                                                             |
| `data-keyrove-enter-key`     | —                                                        | From the focused item into the root nested inside it.                                                                                                                                                                   |

The boolean attributes — `data-keyrove-item`, `data-keyrove-skip`,
`data-keyrove-roving-tabindex`, `data-keyrove-root`, and `data-keyrove-loop` —
are enabled when bare or set to `"true"`; set one to `"false"` to disable it.

Every `*-key` attribute takes `none` as well as a combo, which leaves its move
with no key and its default key to the browser.

Horizontal default arrows reverse under RTL; see
[horizontal groups and RTL](#horizontal-groups-and-rtl).

### Attribute builders

`rootAttributes(options?)` and `itemAttributes(options?)` return plain objects
of `data-keyrove-*` attributes with string values and literal property names
in their types. Spread them into JSX or Svelte markup, use Vue's `v-bind`, or
apply them with `setAttribute`; see [framework examples](/docs/installation#react).

```ts
import { rootAttributes, itemAttributes } from '@mixedrays/keyrove';

rootAttributes({ cols: 3, loop: false, keys: { next: 'KeyJ, ArrowDown' } });
// {
//   'data-keyrove-root': 'true',
//   'data-keyrove-cols': '3',
//   'data-keyrove-loop': 'false',
//   'data-keyrove-next-key': 'KeyJ, ArrowDown'
// }

itemAttributes({ skip: false, rovingTabindex: true, typeahead: 'Inbox' });
// {
//   'data-keyrove-item': 'true',
//   'data-keyrove-skip': 'false',
//   'data-keyrove-roving-tabindex': 'true',
//   'data-keyrove-typeahead': 'Inbox'
// }
```

Both builders always emit their enabled marker, including when called with
no arguments. Booleans become `"true"` or `"false"`, numbers become strings,
and `undefined` fields are omitted. They do not set `tabindex`; give each item
a tab stop or [initialize roving tabindex](/docs/examples/roving-tabindex#setting-the-initial-tab-stop).

The root input shares its fields and types with `GroupOptions`. Move bindings
accept the same combos, comma-separated lists and `'none'`. Bindings are open
[`KeyCombo`](#keycombo) strings, as in `GroupOptions`; the builders do not
validate their spelling.
Per-item `skip` and `rovingTabindex` are booleans, unlike group-wide selectors
and settings. The public input and output types are:

```ts
type RootAttributeOptions = Pick<
  GroupOptions,
  'cols' | 'loop' | 'orientation' | 'pageLength' | 'keys'
>;

type ItemAttributeOptions = {
  skip?: boolean;
  rovingTabindex?: boolean;
  focusKey?: KeyCombo;
  typeahead?: string;
};

// RootAttributes and ItemAttributes name the returned object types.
```

`items`, the `root` selector, group-wide `skip` and `rovingTabindex`, and
`focusKeys` stay options; they have no corresponding root attribute.

For plain DOM code:

```ts
for (const [name, value] of Object.entries(rootAttributes({ loop: true }))) {
  list.setAttribute(name, value);
}
```

The builders have no DOM dependency and can run during server rendering.
Unused builders are tree-shaken away with the rest of the package's unused
exports.

### Constants

Every attribute name is exported as a constant, so markup built in JavaScript
need not hardcode strings. Drop `data-keyrove-`, upper-case the rest with `_`
for `-`, and prefix `KEYROVE_ATTR_`: `data-keyrove-next-row-key` is
`KEYROVE_ATTR_NEXT_ROW_KEY`.

```ts
import { KEYROVE_ATTR_ITEM } from '@mixedrays/keyrove';

const item = document.createElement('li');
item.setAttribute(KEYROVE_ATTR_ITEM, '');
item.tabIndex = 0;
```

## Types

```ts
import type {
  GroupOptions,
  KeyCombo,
  KeyRoveCode,
  KeyRoveEvent,
  KeyRoveOptions,
  Move,
  MoveAction,
  MoveResult,
  InitRovingTabindexOptions,
  ItemAttributeOptions,
  ItemAttributes,
  Options, // the earlier name of KeyRoveOptions
  RootAttributeOptions,
  RootAttributes,
  RovingTabindexOptions,
  StrideAction,
  TypeaheadMove,
  TypeaheadOptions,
  TypeaheadResult,
} from '@mixedrays/keyrove';
```

### KeyRoveEvent

The required event shape. Native keyboard events and compatible framework
events, including React synthetic events, satisfy it.

```ts
type KeyRoveEvent = {
  code: KeyRoveCode;
  target: EventTarget | null;
  currentTarget: EventTarget | null;
  preventDefault: () => void;
  ctrlKey?: boolean;
  altKey?: boolean;
  shiftKey?: boolean;
  metaKey?: boolean;
  isComposing?: boolean;
  defaultPrevented?: boolean;
  key?: string;
};
```

The modifier flags, `isComposing`, `defaultPrevented` and `key` are optional so
a hand-built event object still qualifies. A missing flag reads as "not held",
a missing `isComposing` as "not composing" and a missing `defaultPrevented` as
not [consumed](#return-value). An object of your own that bridges events must
forward them, or every press matches as unmodified and unconsumed. Only
[typeahead](#createtypeahead-options) reads `key`; an event without it
navigates but never typeaheads.

### KeyRoveCode

The `code` an event carries: the physical key, such as `KeyJ` or `ArrowDown`.
Any string is accepted; the union exists so editors complete the codes
keyrove binds by default. It does not validate. Bindings, which add modifiers
and lists, use [`KeyCombo`](#keycombo).

```ts
type KeyRoveCode =
  | 'ArrowUp'
  | 'ArrowDown'
  | 'ArrowLeft'
  | 'ArrowRight'
  | 'Home'
  | 'End'
  | 'PageUp'
  | 'PageDown'
  | (string & {});
```

### KeyCombo

A binding string: one [combo](#combos), such as `'KeyJ'` or
`'ctrl+ArrowDown'`, or a comma-separated list of them, such as
`'ArrowDown, KeyJ'`. It types the `keys` values, `focusKey` in the attribute
builders, and the second argument of
[`matchesCombo`](#matchescombo-event-combo). Where a move is bound, `'none'`
binds it to no key and returns the default key to the browser.

```ts
type KeyCombo = KeyRoveCode; // the same open string, in a binding's role

const next: KeyCombo = 'ArrowDown, ctrl+KeyJ';
const options: KeyRoveOptions = { keys: { next, pageDown: 'none' } };
```

Like `KeyRoveCode`, it accepts any string, including values read from
attributes or data, and does not validate the grammar.

### MoveAction, MoveResult, Move

```ts
type MoveAction =
  | 'home'
  | 'end'
  | 'homeRow' // grid only: first cell of the focused row
  | 'endRow' // grid only: last cell of the focused row
  | 'next' // +1 item in DOM order: a list item, or a grid cell
  | 'prev'
  | 'nextRow' // grid only: +1 row, same column
  | 'prevRow'
  | 'pageUp'
  | 'pageDown'
  | 'exit' // from a nested root to the group around it
  | 'enter' // from an item into the root nested inside it
  | 'focus'; // an element's own data-keyrove-focus-key

// what keyRove returns for a consumed keypress
type MoveResult = {
  action: MoveAction;
  from: Element | null;
  to: Element | null;
};

// what onMove receives: a move that actually happened
type Move = MoveResult & { to: Element };
```

### KeyRoveOptions

What [`keyRove`](#options) and [`rove`](#rove-element-action-options) take:
the group settings and `onMove`. `Options` is its earlier name and remains
exported as the same type.

```ts
type KeyRoveOptions = GroupOptions & { onMove?: (move: Move) => void };

type Options = KeyRoveOptions;
```

### GroupOptions, StrideAction

All group settings are optional; see [options](#options) for fallbacks.
`StrideAction` covers movement through the item sequence. It excludes `exit`,
`enter` and `focus`.

```ts
type GroupOptions = {
  items?: string | ((root: Element) => Element[]);
  root?: string;
  cols?: number | 'auto';
  loop?: boolean;
  orientation?: 'horizontal' | 'vertical';
  pageLength?: number;
  keys?: Partial<Record<StrideAction | 'exit' | 'enter', KeyCombo | 'none'>>;
  focusKeys?: Record<string, string | Element>;
  skip?: string | ((element: Element) => boolean);
  rovingTabindex?: boolean;
};

type StrideAction = Exclude<MoveAction, 'exit' | 'enter' | 'focus'>;
```

### TypeaheadOptions, TypeaheadResult, TypeaheadMove

What [`createTypeahead`](#createtypeahead-options) takes and its handler
returns. The result has `MoveResult`'s shape with its own action.

```ts
type TypeaheadOptions = Pick<
  GroupOptions,
  'items' | 'root' | 'skip' | 'rovingTabindex'
> & {
  label?: (item: Element) => string; // the text an item is matched by
  resetMs?: number; // buffer lifetime, default 500
  matchMode?: 'prefix' | 'cycle'; // how repeated characters match, default 'prefix'
  foldDiacritics?: boolean; // ignore accents and other marks, default true
  onMove?: (move: TypeaheadMove) => void;
};

type TypeaheadResult = {
  action: 'typeahead';
  from: Element | null;
  to: Element | null; // null: the match is the item already focused
};

// what onMove receives: a move that actually happened
type TypeaheadMove = TypeaheadResult & { to: Element };
```

### RovingTabindexOptions, InitRovingTabindexOptions

What [`followFocus`](#followfocus-event-options) and
[`initRovingTabindex`](#initrovingtabindex-root-options) take: the group
settings that decide which elements are the group's roving items, and for
`initRovingTabindex`, the item to give the stop.

```ts
type RovingTabindexOptions = Pick<
  GroupOptions,
  'items' | 'root' | 'skip' | 'rovingTabindex'
>;

type InitRovingTabindexOptions = RovingTabindexOptions & {
  initial?: Element | null; // the item to hold the stop, when it can
};
```

---

Source: https://keyrove.pages.dev/docs/glossary

# Glossary

> The terms these docs use for keyrove's parts and behavior, from group, root and item to combo and roving tabindex, each linked to where it is covered.

| Term            | Definition                                                                                                                                                                                                                                                                 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo           | A key a binding answers to: zero or more of `mod+`, `ctrl+`, `alt+`, `shift+` and `meta+`, then a `KeyboardEvent.code`, such as `ctrl+KeyJ`. A comma-separated list answers to any of its combos. Matching is exact. See [combos](/docs/api#combos).                       |
| Consumed key    | A key keyrove acted on: it called `preventDefault()` and returned a result, whether or not focus moved. A key another handler already consumed is left alone. See [consumed and untouched keys](/docs/api#consumed-and-untouched-keys).                                    |
| Consumed no-op  | A consumed key with nowhere to go, such as next at the end of a list that does not loop. The result's `to` is `null`. See [return value](/docs/api#return-value).                                                                                                          |
| Editable target | A `textarea`, `select` or `[contenteditable]` element, or an `input` whose type uses the arrows itself, such as text, number or range. It keeps its native keys while the arrows move between the rows around it. See [editable targets](/docs/examples/editable-targets). |
| Exit and enter  | The two moves across a nested root's boundary: `enter` focuses the group inside the focused item, and `exit` returns to the item around the nested root. Neither has a default key. See [exit and enter](/docs/api#exit-and-enter).                                        |
| Focus key       | A combo that focuses one element from anywhere under the listener, across roots, set with `data-keyrove-focus-key` or the `focusKeys` option. The element need not be an item. See [focus keys](/docs/examples/focus-keys).                                                |
| Grid            | A group whose column count, `cols`, is above 1. Its items fill rows of that many cells in DOM order, and the arrows move by cell and by row. See [grid](/docs/examples/grid).                                                                                              |
| Group           | The items one root governs, together with the settings read off that root or passed as options. A group is a list, or a grid when it has columns. See [how it works](/docs/introduction#how-it-works).                                                                     |
| Item            | An element keyrove can move focus to: one marked `data-keyrove-item`, or one the `items` option selects. Elements carrying `disabled` are never navigable. See [how it works](/docs/introduction#how-it-works).                                                            |
| Listener        | The element the keydown handler is attached to, the event's `currentTarget`. It stands in as the root when no marked root is found, and bounds how far focus keys and exit reach. See [roots](/docs/api#roots).                                                            |
| Looping         | Next and prev wrapping from the last item to the first and back, set with `data-keyrove-loop` or the `loop` option. Lists only; grids keep their edges. See [looping lists](/docs/examples/looping-lists).                                                                 |
| Navigable item  | An item a move can land on: one that is neither skipped nor disabled. Entering a group, the ends of a list and page jumps all count navigable items only. See [edges and looping](/docs/api#edges-and-looping).                                                            |
| Nested root     | A root inside another group. Only its own bindings apply inside it, it keeps its own roving tab stop, and exit and enter move between it and the group around it. See [nested roots](/docs/examples/nested-roots).                                                         |
| Orientation     | Which arrows a list's next and prev answer to by default: Up and Down for a vertical list, Left and Right for a horizontal one, following the text direction. See [horizontal lists](/docs/examples/horizontal-lists).                                                     |
| Page length     | How far Page Up and Page Down jump: that many rows in a grid, or items in a list. 10 unless `data-keyrove-page-length` or `pageLength` says otherwise. See [page length](/docs/examples/basic#page-length).                                                                |
| Root            | The element that holds a group's items and carries its settings: the nearest element at or above the event target marked `data-keyrove-root`, else the listener. See [roots](/docs/api#roots).                                                                             |
| Roving tabindex | One tab stop per group: the item holding it has `tabindex="0"` and every other item `-1`, so Tab enters and leaves the group in one press, landing on the item that holds the stop. See [roving tabindex](/docs/examples/roving-tabindex).                                 |
| Skipped item    | An item marked `data-keyrove-skip` or matched by the `skip` option. It keeps its place in the sequence, and its cell in a grid, but no move lands on it. See [skipped items](/docs/examples/skipped-items).                                                                |
| Stride action   | A move through the item sequence: `next`, `prev`, `home`, `end`, `pageUp` and `pageDown`, plus `nextRow`, `prevRow`, `homeRow` and `endRow` in a grid. `rove` takes one by name. See [`StrideAction`](/docs/api#groupoptions-strideaction).                                |
| Typeahead       | Focusing an item by typing the start of its label, added with a handler from `createTypeahead`. It works beside `keyRove`, not inside it. See [typeahead](/docs/examples/typeahead).                                                                                       |

---

Source: https://keyrove.pages.dev/docs/about

# About

> What keyrove is, who maintains it, and which version of these docs you are reading.

keyrove provides keyboard navigation for lists, grids and trees, in any
framework and with no runtime dependencies. See the [introduction](/docs/introduction)
for setup and behavior. The project is open source under the
[MIT license](/docs/license); issues and pull requests are welcome.

## This site

- **Package** — [@mixedrays/keyrove](https://www.npmjs.com/package/@mixedrays/keyrove) 2.5.0 on npm
- **Docs version** — 2.11.0, numbered separately from the package
- **Repository** — [github.com/mixedrays/keyrove](https://github.com/mixedrays/keyrove)
- **Author** — [@mixedrays](https://github.com/mixedrays)

To read a page as Markdown, append `.md` to its URL or choose **View as
Markdown** under the page title. **View source** opens its source file under
`packages/docs/content` in the repository.

---

Source: https://keyrove.pages.dev/docs/license

# License

> keyrove and this documentation are MIT licensed, and crawlers, AI agents and model training are all welcome to them.

The library, its source and this documentation are released under the MIT
License. The same text ships as `LICENSE` in the npm package and at the root of
the [repository](https://github.com/mixedrays/keyrove).

## MIT License

Copyright (c) 2026 mixedrays

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## AI and automated access

The documentation lives in the same repository as the code and is covered by
the same license. You may crawl it, give it to an AI agent or assistant, and
use it to train models, with no further permission needed.

- **Crawlers** — [robots.txt](/robots.txt) allows every path to every crawler.
  GPTBot, ClaudeBot, Google-Extended, PerplexityBot and CCBot are named, and
  its `Content-Signal` line allows search, AI input and AI training.
- **Agents** — every page is also served as markdown at its URL plus `.md`.
  [llms.txt](/llms.txt) indexes them, and [llms-full.txt](/llms-full.txt) is
  all of them in one file, the cheaper fetch if you want the whole set.
- **Limits** — the site is static files, with no API, no key and no rate limit
  of its own.

The license's one condition still applies to anything you redistribute: keep
the copyright and permission notice with copies or substantial portions of the
code or docs.

Questions about using keyrove go to the
[issue tracker](https://github.com/mixedrays/keyrove/issues).

---

Source: https://keyrove.pages.dev/docs/examples

# Overview

> Live keyboard navigation examples for lists, grids, trees, menus and listboxes, each a working demo with the code that runs it.

Start with the [basic list](/docs/examples/basic). On every page,
<kbd class="kbd">Tab</kbd> into the demo or click it, then try the keys listed
with it.

## Lists

- [Basic list](/docs/examples/basic) — arrows, <kbd class="kbd">Home</kbd>,
  <kbd class="kbd">End</kbd> and the page keys on a plain list.
- [Looping lists](/docs/examples/looping-lists) — wrap from the last item to
  the first, and back.
- [Horizontal lists](/docs/examples/horizontal-lists) —
  <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> for toolbars and tab rows,
  following the text direction.
- [Custom keys](/docs/examples/custom-keys) — rebind a move, add modifiers, or
  switch a binding off.

## Grids

- [Grid](/docs/examples/grid) — move by cell, row, row ends, grid ends or pages.
- [Responsive grid](/docs/examples/responsive-grid) — read the column count
  from CSS on every keypress.

## Tab stops and focus

- [Roving tabindex](/docs/examples/roving-tabindex) — one tab stop per group,
  following focus.
- [Skipped items](/docs/examples/skipped-items) — pass over headings and
  disabled items.
- [Nested roots](/docs/examples/nested-roots) — inner groups with their own
  keys, and a way back out.
- [Focus keys](/docs/examples/focus-keys) — shortcuts that focus an item or
  panel from anywhere under the listener.
- [Editable targets](/docs/examples/editable-targets) — text fields and
  sliders keep their own keys.

## Widgets

- [Typeahead](/docs/examples/typeahead) — focus an item by typing its label.
- [Tree view](/docs/examples/tree-view) — navigate visible rows while your
  code opens and closes branches.
- [Options in JavaScript](/docs/examples/javascript-options) — a menu
  configured without changing its markup.
- [Listbox](/docs/examples/listbox) — navigation, typeahead, roving tabindex
  and selection in one widget.

---

Source: https://keyrove.pages.dev/docs/examples/basic

# Basic list

> Add keyboard navigation to a list with one keydown listener, keep its normal tab order, and react to each move with onMove.

Add `data-keyrove-item` and `tabindex="0"` to each list item, then attach a
`keydown` listener to the container.

<kbd class="kbd">Tab</kbd> to an item or click it to try the demo:

- <kbd class="kbd">↑</kbd> / <kbd class="kbd">↓</kbd> move one item.
- <kbd class="kbd">Home</kbd> / <kbd class="kbd">End</kbd> jump to the first or last item.
- <kbd class="kbd">PageUp</kbd> / <kbd class="kbd">PageDown</kbd> move in blocks.

```html
<ul id="countries" data-keyrove-page-length="5">
  <li data-keyrove-item tabindex="0">Argentina</li>
  <li data-keyrove-item tabindex="0">Australia</li>
  <li data-keyrove-item tabindex="0">Belgium</li>
  <!-- … -->
  <li data-keyrove-item tabindex="0">Italy</li>
</ul>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

const list = document.querySelector<HTMLElement>('#countries')!;
list.addEventListener('keydown', (e) => keyRove(e));
```

<kbd class="kbd">Tab</kbd> still visits every item. Use
[roving tabindex](/docs/examples/roving-tabindex) to make the list a single tab
stop, or [custom keys](/docs/examples/custom-keys) to change the bindings.

## Page length

Set `data-keyrove-page-length` on the container to choose how many items
<kbd class="kbd">PageUp</kbd> and <kbd class="kbd">PageDown</kbd> move. The
default is `10`; this twelve-item demo uses `5`. Jumps stop at the first or
last item.

At either end, pressing a key to move farther keeps focus in place and prevents
the browser's default action. See [looping lists](/docs/examples/looping-lists)
to wrap to the other end.

## Reacting to movement

Pass `onMove` in the second argument to run a callback after focus moves.
It only fires when focus actually changes. This argument also accepts
[settings](/docs/attributes-and-options) in place of HTML attributes.

```ts
list.addEventListener('keydown', (e) => {
  keyRove(e, {
    onMove: ({ action, to }) => console.log(action, '→', to),
  });
});
```

The readout at the top of the demo shows three outcomes:

- **Indigo:** focus moved; `onMove` fired.
- **Amber:** keyrove handled the key, but focus stayed in place.
- **Gray:** keyrove left the key to the browser.

Amber and gray readouts use `keyRove`'s [return value](/docs/api#return-value).
Other handlers can use it to check whether keyrove handled the key.

---

Source: https://keyrove.pages.dev/docs/examples/looping-lists

# Looping lists

> Make keyboard navigation wrap from the last item to the first and back again, and decide when a list should loop and when it should stop at its ends.

By default, navigation stops at the first and last items. Add
`data-keyrove-loop` to the container to wrap between them:

- <kbd class="kbd">↓</kbd> from _Sign out_ moves to _Profile_.
- <kbd class="kbd">↑</kbd> from _Profile_ moves to _Sign out_.

You can sign out any time you like, but the arrows will never leave.
<kbd class="kbd">Tab</kbd> will.

```html
<ul id="account-menu" data-keyrove-loop>
  <li data-keyrove-item tabindex="0">Profile</li>
  <li data-keyrove-item tabindex="0">Settings</li>
  <li data-keyrove-item tabindex="0">Keyboard shortcuts</li>
  <li data-keyrove-item tabindex="0">Help</li>
  <li data-keyrove-item tabindex="0">Sign out</li>
</ul>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

const menu = document.querySelector<HTMLElement>('#account-menu')!;
menu.addEventListener('keydown', (e) => keyRove(e));
```

keyrove reads the attribute on every keypress. You can turn looping on or off
without changing the listener or reinitializing the group.

## Boolean value

Both `data-keyrove-loop` and `data-keyrove-loop="true"` enable looping.
Set `data-keyrove-loop="false"` to disable it. The same rule applies to all
boolean keyrove attributes, including `data-keyrove-item`, `data-keyrove-root`,
`data-keyrove-skip`, and `data-keyrove-roving-tabindex`.

In JSX, pass a boolean directly:

```tsx
<ul data-keyrove-loop={loop}>…</ul>
```

## Entering at either end

When no item is focused and the group's listener receives a directional key,
keyrove focuses the first navigable item. In a looping list, `prev` enters at
the last navigable item instead. With the default bindings:

- <kbd class="kbd">↓</kbd> enters at the first item.
- <kbd class="kbd">↑</kbd> enters at the last item.

This matches the optional arrow-key entry behavior in the
[APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
pattern.

<kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd>, and the page keys still require focus inside an item.

## Only next and prev wrap

Looping changes only `next` and `prev`:

- <kbd class="kbd">Home</kbd> and <kbd class="kbd">End</kbd> move to the first
  and last navigable items.
- <kbd class="kbd">PageUp</kbd> and <kbd class="kbd">PageDown</kbd> stop at
  either end if a jump would go past it.

If you rebind `next` and `prev` to <kbd class="kbd">J</kbd> and
<kbd class="kbd">K</kbd>, those keys wrap and the arrows return to their browser
defaults. See
[custom keys](/docs/examples/custom-keys).

## Skipped items keep their place

A wrap lands on the first or last navigable item, passing over items marked
`data-keyrove-skip` or `disabled`. See [skipped items](/docs/examples/skipped-items).

## Nowhere to go

If the only navigable item already has focus, `next` and `prev` leave it there.
keyrove still calls `preventDefault()`, but `onMove` does not fire.
For `next`, the [return value](/docs/api#return-value) is
`{ action: 'next', from, to: null }`, just as at the end of a non-looping list.

## Grids keep their edges

Looping applies only to lists. When `data-keyrove-cols` is greater than `1`,
the group is a [grid](/docs/examples/grid) and ignores `data-keyrove-loop`.
Cell moves continue across row boundaries, but stop at the first or last cell;
row moves stop at the top or bottom. At these edges, keyrove prevents the
browser's default action without moving focus. See the
[APG grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) for keyboard
navigation guidance.

## When a list should wrap

Wrapping works well for short menus, pickers, and tab lists where both ends
are visible.

For long, scrolling lists, keeping the ends helps users track their position.
Wrapping can unexpectedly jump the viewport back to the top and may be hard to
notice with a screen reader. Without looping, holding <kbd class="kbd">↓</kbd>
at the bottom keeps focus there and prevents the page from scrolling.

---

Source: https://keyrove.pages.dev/docs/examples/custom-keys

# Custom keys

> Rebind keyboard navigation to any KeyboardEvent.code, add modifier combinations, bind several keys to one move, or switch a move off.

Set `data-keyrove-next-key` and `data-keyrove-prev-key` on the root to change
the navigation keys. Values are
[`KeyboardEvent.code`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code)
values, with optional [modifiers](#modifiers).

This toolbar uses <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> to move between buttons. <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> keep their
browser behavior.

```html
<div
  id="toolbar"
  data-keyrove-next-key="ArrowRight"
  data-keyrove-prev-key="ArrowLeft"
>
  <button data-keyrove-item tabindex="0">Bold</button>
  <button data-keyrove-item tabindex="0">Italic</button>
  <button data-keyrove-item tabindex="0">Underline</button>
  <!-- … -->
  <button data-keyrove-item tabindex="0">Code</button>
</div>
```

```html
<div data-keyrove-next-key="ArrowRight" data-keyrove-prev-key="ArrowLeft">
  …
</div>
```

The handler stays `keyRove(e)`. Only bound keys are handled. Press <kbd class="kbd">↓</kbd> in the
toolbar to see an unhandled key in the readout; the browser can still scroll.

## Horizontal lists

For <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> navigation that follows text direction, use:

```html
<div data-keyrove-orientation="horizontal">…</div>
```

It makes `ArrowRight` / `ArrowLeft` the defaults and flips them under RTL, so
the "forward" arrow follows the text. Reach for the explicit key attributes when
the keys are anything other than the reading-direction arrows; they win over
orientation wherever both are set.
[Horizontal lists](/docs/examples/horizontal-lists) shows both directions.

## Any key, not a shortlist

The attribute value is a combo, an optional set of modifiers and a
`KeyboardEvent.code`, matched against the event on every press. There is no set
of supported keys to choose from:

```html
<!-- vim-style, for a results list in a keyboard-first app -->
<ul data-keyrove-next-key="KeyJ" data-keyrove-prev-key="KeyK">
  …
</ul>

<!-- game-style -->
<ul data-keyrove-next-key="KeyS" data-keyrove-prev-key="KeyW">
  …
</ul>

<!-- the number pad, for a kiosk with no arrow cluster -->
<ul data-keyrove-next-key="Numpad2" data-keyrove-prev-key="Numpad8">
  …
</ul>
```

Each root is read on its own, so two groups on the same page can answer to
different keys with one delegated listener serving both.

## Several keys for one move

A binding replaces the default, so the vim-style list above gives up the
arrows: <kbd class="kbd">↓</kbd> goes back to scrolling the page. To keep them,
list both, separated by commas. The move answers to any key in the list:

```html
<ul
  data-keyrove-next-key="ArrowDown, KeyJ"
  data-keyrove-prev-key="ArrowUp, KeyK"
>
  …
</ul>
```

```ts
keyRove(e, { keys: { next: 'ArrowDown, KeyJ', prev: 'ArrowUp, KeyK' } });
```

A list is as literal as a single combo, so the arrow you keep is the one you
name. Nothing flips under RTL, and nothing is added back for you.

## Modifiers

Prefix the code with any of `mod+`, `ctrl+`, `alt+`, `shift+`, `meta+`; the
longer `control`, `option`, `cmd` and `command` spell the same modifiers. `mod`
is <kbd class="kbd">Cmd</kbd> on Apple platforms and <kbd class="kbd">Ctrl</kbd>
elsewhere:

```html
<ul
  data-keyrove-next-key="ctrl+ArrowRight"
  data-keyrove-prev-key="ctrl+ArrowLeft"
>
  …
</ul>
```

Matching is exact in both directions. A bare `KeyJ` means "<kbd class="kbd">J</kbd> with nothing else
held", so <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">J</kbd> keeps its
browser default, and a `ctrl+KeyJ` binding never fires on a plain
<kbd class="kbd">J</kbd>. The full grammar is in the
[API reference](/docs/api#combos).

## Codes, not keys

These are `KeyboardEvent.code` values, physical keys, not `KeyboardEvent.key`
values: `KeyW` rather than `w`. The code does not change with the keyboard
layout, so a binding chosen for QWERTY lands on the same physical key on AZERTY.

Choose letter bindings with keyboard layout in mind. For example, the physical
positions `KeyJ` and `KeyK` produce `c` and `t` on Dvorak.

## <kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd> and the page keys

<kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd>,
<kbd class="kbd">PageUp</kbd> and <kbd class="kbd">PageDown</kbd> are defaults
too. `data-keyrove-home-key`, `data-keyrove-end-key`,
`data-keyrove-page-up-key` and `data-keyrove-page-down-key` rebind them by the
same [rules](/docs/api#keys):

```html
<!-- vim-style, all the way down -->
<ul
  data-keyrove-next-key="KeyJ"
  data-keyrove-prev-key="KeyK"
  data-keyrove-home-key="KeyG"
  data-keyrove-end-key="shift+KeyG"
  data-keyrove-page-down-key="ctrl+KeyD"
  data-keyrove-page-up-key="ctrl+KeyU"
>
  …
</ul>
```

Whatever they are bound to, these moves act only once focus is inside an item.
Only the directional keys
[enter a group](/docs/api#consumed-and-untouched-keys).

## Switching a move off

Some groups should not have every move. The
[APG toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) has no page
keys, so <kbd class="kbd">PageDown</kbd> on one of its buttons should scroll
the page, not jump to the last button. `none` binds a move to no key and
hands its default back to the browser:

```html
<div
  role="toolbar"
  data-keyrove-orientation="horizontal"
  data-keyrove-page-up-key="none"
  data-keyrove-page-down-key="none"
>
  …
</div>
```

```ts
keyRove(e, {
  orientation: 'horizontal',
  keys: { pageUp: 'none', pageDown: 'none' },
});
```

Every other move keeps its key. An empty attribute is not the same thing: it
counts as unset, so the move keeps its default.

## Grids

The attributes keep their meaning in a grid, and the row and grid-wide moves get
pairs of their own:

| Move                                 | Attribute                                                 | Default (LTR)              |
| ------------------------------------ | --------------------------------------------------------- | -------------------------- |
| Next / previous cell                 | `data-keyrove-next-key` / `data-keyrove-prev-key`         | `ArrowRight` / `ArrowLeft` |
| Next / previous row, same column     | `data-keyrove-next-row-key` / `data-keyrove-prev-row-key` | `ArrowDown` / `ArrowUp`    |
| First / last cell of the focused row | `data-keyrove-home-row-key` / `data-keyrove-end-row-key`  | `Home` / `End`             |
| First / last cell of the grid        | `data-keyrove-home-key` / `data-keyrove-end-key`          | `ctrl+Home` / `ctrl+End`   |

Each pair rebinds independently. A full vim-style grid binds all four arrows:

```html
<div
  data-keyrove-cols="6"
  data-keyrove-prev-key="KeyH"
  data-keyrove-next-key="KeyL"
  data-keyrove-prev-row-key="KeyK"
  data-keyrove-next-row-key="KeyJ"
>
  …
</div>
```

As always, [one keypress resolves to one action](/docs/api#precedence): bind
`data-keyrove-next-key="ArrowDown"` and the default row move stands down.
Explicit bindings are literal under RTL, too; only the
[default arrows follow the reading direction](/docs/api#horizontal-groups-and-rtl).

## An item's own key

Everything above binds a _move_ on the root. An item can also carry a combo of
its own, and so can an element that is not one:
`data-keyrove-focus-key="ctrl+shift+KeyE"` focuses it from anywhere under the
listener and outranks the root's bindings.
[Focus keys](/docs/examples/focus-keys) has the rules in full.

## Editable elements are exempt

Movement bindings do not run inside text fields, selects or editable content.
Those elements keep their editing keys. Modified focus shortcuts are an
exception; see [editable targets](/docs/examples/editable-targets) and the
[API rules](/docs/api#editable-targets).

## A binding worth avoiding

**`Tab` itself.** `data-keyrove-next-key="Tab"` works, and it costs the group
the browser's own forward tab navigation.
<kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd> is a different combo, so
it stays native and remains the way out, but a group where the two
<kbd class="kbd">Tab</kbd> directions behave that differently is confusing. If
you want <kbd class="kbd">Tab</kbd> to move past a group rather than through it,
[roving tabindex](/docs/examples/roving-tabindex) does that and leaves the key
alone.

---

Source: https://keyrove.pages.dev/docs/examples/horizontal-lists

# Horizontal lists

> Navigate a horizontal list or toolbar with the Left and Right arrow keys, with defaults that follow the text direction in right-to-left layouts.

Set `data-keyrove-orientation="horizontal"` on a list's root to use
<kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd>. In left-to-right text, <kbd class="kbd">→</kbd> moves to the next item and <kbd class="kbd">←</kbd> to the
previous one. <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> keep their browser behavior.

```html
<div id="filters" data-keyrove-orientation="horizontal">
  <button data-keyrove-item tabindex="0">All</button>
  <button data-keyrove-item tabindex="0">Unread</button>
  <button data-keyrove-item tabindex="0">Starred</button>
  <button data-keyrove-item tabindex="0">Snoozed</button>
  <button data-keyrove-item tabindex="0">Drafts</button>
</div>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

document
  .querySelector('#filters')
  .addEventListener('keydown', (e) => keyRove(e));
```

<kbd class="kbd">Home</kbd>/<kbd class="kbd">End</kbd> still jump to the ends, <kbd class="kbd">PageUp</kbd>/<kbd class="kbd">PageDown</kbd> still move a page, and <kbd class="kbd">Tab</kbd>
keeps its default behavior. Moves follow DOM order. Lists are vertical unless
the orientation is set to the literal value `horizontal`.

## Right to left

Under `dir="rtl"`, the defaults reverse: <kbd class="kbd">←</kbd> is next and <kbd class="kbd">→</kbd> is previous.
This keeps navigation aligned with items laid out in right-to-left order.

```html
<div id="filters-rtl" dir="rtl" data-keyrove-orientation="horizontal">
  <button data-keyrove-item tabindex="0">الكل</button>
  <button data-keyrove-item tabindex="0">غير المقروءة</button>
  <button data-keyrove-item tabindex="0">المميّزة بنجمة</button>
  <button data-keyrove-item tabindex="0">المؤجلة</button>
  <button data-keyrove-item tabindex="0">المسودات</button>
</div>
```

Compare the readouts: <kbd class="kbd">→</kbd> reports `next` in the first bar and `prev` in the RTL
bar. The action names describe movement through DOM order.

The direction comes from the nearest `dir` attribute at or above the root, and
otherwise from the computed style, so a `dir` on `<html>` is enough for every
group on the page. Like every other attribute it is read on the keypress, so a
page that switches language switches its arrows with it. The
[API reference](/docs/api#horizontal-groups-and-rtl) has the resolution rules.

## Explicit keys stay literal

An explicit `data-keyrove-next-key` or `data-keyrove-prev-key` wins over the
orientation, and it is never flipped: it names a physical key and means that
key in either direction.

```html
<!-- Right is next and Left is previous, in LTR and in RTL alike -->
<div data-keyrove-next-key="ArrowRight" data-keyrove-prev-key="ArrowLeft">
  …
</div>
```

Use orientation for arrows that follow text direction. Use explicit bindings
for fixed keys; see [custom keys](/docs/examples/custom-keys).

## Grids

A grid needs no orientation. Its next and prev moves already run along the
row, on the reading-direction arrows, and its row moves take
<kbd class="kbd">↑</kbd> <kbd class="kbd">↓</kbd>. The attribute is ignored
once `data-keyrove-cols` is above `1`; see [grid](/docs/examples/grid), and
its [right-to-left](/docs/examples/grid#right-to-left-grids) section for how
the cell arrows flip.

## Wrapping a strip

Add `data-keyrove-loop` to wrap next/previous at the ends. Under RTL, <kbd class="kbd">←</kbd>
wraps forward. See [looping lists](/docs/examples/looping-lists) for entry
behavior and the moves that do not wrap.

## Telling users about it

keyrove reads its own attribute, not `aria-orientation`. A `role="toolbar"` or
`role="tablist"` is horizontal by default in ARIA, so nothing more is needed
there; a `role="listbox"` or `role="menu"` laid out sideways should carry
`aria-orientation="horizontal"` alongside, so assistive technology announces
the arrows the group actually answers to.

---

Source: https://keyrove.pages.dev/docs/examples/grid

# Grid

> Add arrow-key navigation to a grid. Set the column count, then move by cell, row, row ends, grid ends or pages, with arrows that flip in right-to-left text.

Set `data-keyrove-cols` above `1` to navigate a grid. <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move one row in
the same column; <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> move one cell in DOM order.

```html
<div id="time-slots" data-keyrove-cols="6" data-keyrove-page-length="2">
  <button data-keyrove-item tabindex="0">09:00</button>
  <button data-keyrove-item tabindex="0">09:30</button>
  <button data-keyrove-item tabindex="0">10:00</button>
  <!-- … -->
  <button data-keyrove-item tabindex="0">17:30</button>
</div>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

document
  .querySelector('#time-slots')
  .addEventListener('keydown', (e) => keyRove(e));
```

The demo sets `data-keyrove-cols="6"` and `data-keyrove-page-length="2"`, so a
page is two rows. The column count is the one keyrove navigates by, so keep it
in step with the layout: a CSS `grid-template-columns` of six and a
`data-keyrove-cols` of four will move focus in a way that does not match what is
on screen.

## Moves in a grid

| Move             | Default key                                                                                                      | Attribute                                                 | At the edge                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Next cell        | <kbd class="kbd">→</kbd>                                                                                         | `data-keyrove-next-key`                                   | Flows on to the next row's first cell; stops at the grid's last cell                          |
| Previous cell    | <kbd class="kbd">←</kbd>                                                                                         | `data-keyrove-prev-key`                                   | Flows back to the previous row's last cell; stops at the first cell                           |
| Next row         | <kbd class="kbd">↓</kbd>                                                                                         | `data-keyrove-next-row-key`                               | Same column; stops at the bottom                                                              |
| Previous row     | <kbd class="kbd">↑</kbd>                                                                                         | `data-keyrove-prev-row-key`                               | Same column; stops at the top                                                                 |
| Row start / end  | <kbd class="kbd">Home</kbd> / <kbd class="kbd">End</kbd>                                                         | `data-keyrove-home-row-key` / `data-keyrove-end-row-key`  | First / last navigable cell of the focused row                                                |
| Grid start / end | <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Home</kbd> / <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">End</kbd> | `data-keyrove-home-key` / `data-keyrove-end-key`          | First / last navigable cell of the grid                                                       |
| Page             | <kbd class="kbd">PageDown</kbd> / <kbd class="kbd">PageUp</kbd>                                                  | `data-keyrove-page-down-key` / `data-keyrove-page-up-key` | `page-length` rows, same column; an overshoot lands on the grid's last / first navigable cell |

- A cell move follows DOM order, like a caret in text, so the cell pair reaches
  every cell in the grid.
- Grids never wrap; [`data-keyrove-loop`](/docs/examples/looping-lists) is
  ignored.
- A grid is entered from outside by any of its four arrows, landing on the
  first cell.
- Rebind any move and the replaced default goes back to its browser behavior;
  see [custom keys](/docs/examples/custom-keys#grids).

At an edge, the key is still consumed and the readout shows an amber no-op.
Holding <kbd class="kbd">↓</kbd> at the bottom of the grid therefore does not scroll the page.

## Right-to-left grids

Under `dir="rtl"` the default cell arrows flip: <kbd class="kbd">←</kbd> is the
next cell and <kbd class="kbd">→</kbd> the previous, each still moving the way
it points on screen. The row arrows and any explicit binding stay put. See
[horizontal groups and RTL](/docs/api#horizontal-groups-and-rtl) for how the
direction is resolved.

## Responsive grids

The column count is read from the attribute on every keypress, not cached, so a
grid whose layout changes only needs the attribute kept current.
[Responsive grid](/docs/examples/responsive-grid) lets the stylesheet decide it.

---

Source: https://keyrove.pages.dev/docs/examples/responsive-grid

# Responsive grid

> Keyboard navigation for a responsive CSS grid, with the column count read from the layout on every keypress so breakpoints stay in CSS.

Set `data-keyrove-cols="auto"` on the grid container to read its column count
from CSS on every keypress. Navigation then follows layout changes without
copying breakpoints into JavaScript.

This demo uses a
[container query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries).
Drag the corner of the dashed frame or narrow the window, then try the arrows.
With six columns, <kbd class="kbd">↓</kbd> moves from January to July; with two, it moves to March.

```html
<div id="month-picker">
  <style>
    #month-picker {
      container-type: inline-size;
    }

    #months {
      --cols: 2;
      display: grid;
      grid-template-columns: repeat(var(--cols), minmax(0, 1fr));
      gap: 0.375rem;
    }

    @container (min-width: 20rem) {
      #months {
        --cols: 3;
      }
    }

    @container (min-width: 28rem) {
      #months {
        --cols: 4;
      }
    }

    @container (min-width: 36rem) {
      #months {
        --cols: 6;
      }
    }
  </style>

  <div id="months" data-keyrove-root data-keyrove-cols="auto">
    <button data-keyrove-item tabindex="0">January</button>
    <button data-keyrove-item tabindex="0">February</button>
    <button data-keyrove-item tabindex="0">March</button>
    <!-- … -->
    <button data-keyrove-item tabindex="0">December</button>
  </div>
</div>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

// <div id="months" data-keyrove-cols="auto">
document
  .querySelector('#months')
  .addEventListener('keydown', (e) => keyRove(e));
```

Or, where the markup is not yours, as an option:

```ts
keyRove(e, { items: '.month', cols: 'auto' });
```

The demo's grid carries `data-keyrove-root` only because the site's listener
sits on the panel around it. With the listener on the grid itself, as above, the
attribute is not needed.

## Counted on every keypress

`auto` reads the root's computed `grid-template-columns` during each call.
No resize listener or observer is needed to keep the count current.

## The stylesheet owns the breakpoints

The panel declares itself a container with `container-type: inline-size`; the
grid inside sets `--cols` and lays itself out with
`grid-template-columns: repeat(var(--cols), minmax(0, 1fr))`; each `@container`
rule changes the property and nothing else. Add a breakpoint, or move one, and
navigation follows without a JavaScript edit.

The query measures the panel's width, so the grid also adapts when placed in a
sidebar. The panel is the query container because an element cannot query its
own size.

## When the count is implicit

A grid built on `repeat(auto-fill, minmax(8rem, 1fr))` never states a count;
the browser decides how many tracks fit. `auto` needs nothing more for it: the
computed value lists the tracks the browser made, so they are counted the same
way.

## What auto counts

- The root must be the grid container, with one item per cell in DOM order.
  Each item must span one track. Spanning items, subgrids and row wrappers do
  not match this navigation model, including when `items` selects descendants.
- Named lines, such as `[full-start]`, are not counted as columns.
- If the computed value does not resolve to a list of pixel track sizes, the
  count falls back to one and the group navigates as a list. This includes a
  flex container or a grid that is not laid out.

## Layouts that are not grids

A `flex-wrap` row has no track list to count, so `auto` sees one column. Copy
the count in yourself instead, right before the call. Here the stylesheet
publishes it as `--cols`:

```ts
months.addEventListener('keydown', (e) => {
  months.setAttribute(
    'data-keyrove-cols',
    getComputedStyle(months).getPropertyValue('--cols'),
  );
  keyRove(e);
});
```

keyrove reads the attribute fresh on every keypress, so refreshing it in the
same handler is all the synchronization this needs. If something else needs
the attribute between keypresses, such as a test asserting on it, a
`ResizeObserver` on the container can make the same copy whenever the size
changes.

---

Source: https://keyrove.pages.dev/docs/examples/tree-view

# Tree view

> Build a tree view with keyboard navigation. The arrow keys move through visible rows, your code opens and closes branches, and typeahead finds items by name.

Use keyrove to navigate a tree's visible rows. Your widget handles opening
and closing branches and excludes hidden rows from navigation.

This sidebar uses attributes. <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move between visible rows, <kbd class="kbd">→</kbd> opens a
folder, and <kbd class="kbd">←</kbd> closes it. Folders are buttons, so <kbd class="kbd">Enter</kbd>, <kbd class="kbd">Space</kbd> and clicks
also toggle them.

```html
<ul id="docs-nav">
  <li>
    <button data-keyrove-item aria-expanded="true">Guide</button>
    <ul>
      <li><button data-keyrove-item>Introduction</button></li>
      <li><button data-keyrove-item>Installation</button></li>
    </ul>
  </li>
  <li>
    <button data-keyrove-item aria-expanded="false">Examples</button>
    <ul hidden>
      <li><button data-keyrove-item data-keyrove-skip>Basic list</button></li>
      <li><button data-keyrove-item data-keyrove-skip>Grid</button></li>
    </ul>
  </li>
  <li><button data-keyrove-item>API reference</button></li>
</ul>
```

```ts
import { keyRove, matchesCombo } from '@mixedrays/keyrove';

const nav = document.querySelector('#docs-nav');

const setOpen = (folder, open) => {
  folder.setAttribute('aria-expanded', String(open));
  folder.nextElementSibling.hidden = !open;

  for (const item of nav.querySelectorAll('[data-keyrove-item]')) {
    item.toggleAttribute('data-keyrove-skip', !!item.closest('[hidden]'));
  }
};

const fold = (e) => {
  const open = matchesCombo(e, 'ArrowRight');
  if (!open && !matchesCombo(e, 'ArrowLeft')) return null;
  if (e.target.getAttribute('aria-expanded') !== String(!open)) return null;

  e.preventDefault();
  setOpen(e.target, open);

  return e.target;
};

nav.addEventListener('keydown', (e) => keyRove(e) || fold(e));

nav.addEventListener('click', (e) => {
  const folder = e.target.closest('[aria-expanded]');
  if (folder) setOpen(folder, folder.getAttribute('aria-expanded') === 'false');
});
```

Mark each row's button with `data-keyrove-item`. Avoid marking a `<li>` that
contains child items: when items nest, keyrove treats the first item in DOM
order that contains focus as the current item.

Hidden rows remain in the DOM. `setOpen` updates `data-keyrove-skip` after
each toggle so navigation passes over rows inside hidden lists. See
[skipped items](/docs/examples/skipped-items).

`fold` handles <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> only when they change a folder's state. On a page,
or when the folder is already in the requested state, it returns `null` and
leaves the key to the browser.

## Why <kbd class="kbd">←</kbd> and <kbd class="kbd">→</kbd> are not keyrove's

Expanding a branch and moving to a parent require knowledge of the tree's
structure. Add those actions in your widget's handler, as the listbox adds
[selection](/docs/examples/listbox#the-pieces).

A vertical list leaves <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> unbound. `keyRove` returns `null` for them,
so `keyRove(e) || fold(e)` passes them to your handler.

## A full tree view

The file explorer adds `role="tree"`, roving tabindex, typeahead and branch
navigation from the [APG tree pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
It uses [options](/docs/examples/javascript-options) to select rows and skip
hidden descendants directly from the DOM.

- <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move between visible rows; <kbd class="kbd">Home</kbd>/<kbd class="kbd">End</kbd> move to the first/last.
- <kbd class="kbd">→</kbd> opens a closed folder or enters an open folder's first row.
- <kbd class="kbd">←</kbd> closes an open folder or moves to the parent folder.
- Typing finds a row by name. Clicking a folder toggles it.

```html
<ul id="files" role="tree" aria-label="Project files">
  <li role="none">
    <div
      role="treeitem"
      aria-expanded="true"
      aria-owns="files-src"
      tabindex="0"
    >
      src
    </div>
    <ul id="files-src" role="group">
      <li role="none">
        <div
          role="treeitem"
          aria-expanded="false"
          aria-owns="files-components"
          tabindex="-1"
        >
          components
        </div>
        <ul id="files-components" role="group" hidden>
          <li role="none"><div role="treeitem" tabindex="-1">Menu.tsx</div></li>
          <!-- … -->
          <li role="none"><div role="treeitem" tabindex="-1">Tree.tsx</div></li>
        </ul>
      </li>
      <li role="none">
        <div
          role="treeitem"
          aria-expanded="false"
          aria-owns="files-utils"
          tabindex="-1"
        >
          utils
        </div>
        <ul id="files-utils" role="group" hidden>
          <li role="none"><div role="treeitem" tabindex="-1">dom.ts</div></li>
          <li role="none"><div role="treeitem" tabindex="-1">keys.ts</div></li>
        </ul>
      </li>
      <li role="none"><div role="treeitem" tabindex="-1">main.ts</div></li>
      <!-- … -->
    </ul>
  </li>
  <!-- … -->
  <li role="none"><div role="treeitem" tabindex="-1">package.json</div></li>
  <li role="none"><div role="treeitem" tabindex="-1">README.md</div></li>
  <li role="none"><div role="treeitem" tabindex="-1">tsconfig.json</div></li>
</ul>
```

```ts
import {
  createTypeahead,
  keyRove,
  matchesCombo,
  toggleTabIndex,
} from '@mixedrays/keyrove';

const tree = document.querySelector('#files');

const config = {
  items: '[role="treeitem"]',
  skip: '[hidden] [role="treeitem"]',
  rovingTabindex: true,
};

const typeahead = createTypeahead(config);

const groupOf = (item) =>
  document.getElementById(item.getAttribute('aria-owns'));

const parentOf = (item) =>
  item.closest('[role="group"]')?.previousElementSibling;

const toggle = (item, open) => {
  item.setAttribute('aria-expanded', String(open));
  groupOf(item).hidden = !open;
};

const moveTo = (from, to) => {
  toggleTabIndex({ root: from, isActive: false });
  toggleTabIndex({ root: to, isActive: true });
  to.focus();
};

const branch = (e) => {
  const item = e.target.closest('[role="treeitem"]');
  if (!item) return null;

  const expanded = item.getAttribute('aria-expanded'); // null on a file
  const parent = parentOf(item);

  if (matchesCombo(e, 'ArrowRight') && expanded === 'false') {
    toggle(item, true);
  } else if (matchesCombo(e, 'ArrowRight') && expanded === 'true') {
    moveTo(item, groupOf(item).querySelector('[role="treeitem"]'));
  } else if (matchesCombo(e, 'ArrowLeft') && expanded === 'true') {
    toggle(item, false);
  } else if (matchesCombo(e, 'ArrowLeft') && parent) {
    moveTo(item, parent);
  } else {
    return null;
  }

  e.preventDefault();

  return item;
};

tree.addEventListener('keydown', (e) => {
  keyRove(e, config) || typeahead(e) || branch(e);
});

tree.addEventListener('click', (e) => {
  const item = e.target.closest('[role="treeitem"]');
  if (!item) return;

  moveTo(tree.querySelector('[tabindex="0"]'), item);

  const expanded = item.getAttribute('aria-expanded');
  if (expanded) toggle(item, expanded === 'false');
});
```

The readout shows keyrove's moves and the tree's own actions in the same
indigo; the verb tells them apart. From _components_, <kbd class="kbd">↓</kbd>
reads _next → utils_, and <kbd class="kbd">→</kbd> then reads
_expanded → utils_.

### The pieces

- **The markup.** `role="tree"` on the list, `role="treeitem"` on every row,
  `role="group"` on each folder's rows, and `role="none"` on the `<li>`
  elements between them, so their list semantics do not compete with the
  tree's. A folder carries `aria-expanded`, and a closed folder's group is
  `hidden`. The roles and states are
  [left to you](/docs/introduction#what-it-leaves-to-you); keyrove reads them
  here only because the config names the rows by their role.
- **Rows, not list items, are the treeitems.** For the reason the sidebar's
  buttons are its items, each row is a treeitem of its own, with its folder's
  group beside it rather than inside it. `aria-owns` ties the two together for
  assistive technology. That is the shape of the APG's
  [navigation treeview](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/).
- **Navigation.** `items` names the rows, and `skip` passes over any row inside
  a `hidden` group. A closed folder's rows are still in the DOM, so they are
  still items; `skip` keeps <kbd class="kbd">↓</kbd>,
  <kbd class="kbd">End</kbd> and the page keys on the rows that are on screen.
  The selector is asked on every keypress, so opening a folder puts its rows in
  the order with nothing to call. See
  [skipped items](/docs/examples/skipped-items).
- **One tab stop.** `rovingTabindex: true`, with `tabindex="0"` on the first
  row and `-1` on the rest, so <kbd class="kbd">Tab</kbd> treats the tree as
  one control and comes back to the row you left. See
  [roving tabindex](/docs/examples/roving-tabindex).
- **Typeahead.** `createTypeahead` gets the same `config`, so it skips the
  hidden rows too. With _components_ closed, <kbd class="kbd">T</kbd> lands on
  _tsconfig.json_; open it, and <kbd class="kbd">T</kbd> finds _Tabs.tsx_
  first. See [typeahead](/docs/examples/typeahead).
- **Opening and closing.** `branch`, third in the chain, is the widget's own.
  It covers the four cases the APG gives the two arrows, and returns `null` for
  a key it leaves alone:
  <kbd class="kbd">→</kbd> on a file, or <kbd class="kbd">←</kbd> on a closed
  folder at the top. The browser keeps those keys, and a fourth handler could
  chain on.
- **The mouse.** A click focuses a row natively, but it leaves the tab stop
  where the keyboard last put it. The click handler moves the stop with
  `moveTo`, then opens or closes the folder it landed on.

## Variations

- **<kbd class="kbd">Enter</kbd>.** The APG has <kbd class="kbd">Enter</kbd> perform a row's default
  action: open the file, or open or close the folder. In the full tree that is
  one more case in `branch`, on `matchesCombo(e, 'Enter')`; the sidebar's
  buttons have it already.
- **Selection.** Add `aria-selected` to selectable rows and a selection
  handler like the [listbox's](/docs/examples/listbox#the-pieces). For multiple
  selection, add `aria-multiselectable="true"` and implement toggling each
  row's selection.
- **Rows loaded on open.** Fill a folder's group before un-hiding it. The rows
  are read on every keypress, so rows that arrive join the order with nothing
  to call.
- **<kbd class="kbd">\*</kbd> to open siblings.** The APG's optional
  <kbd class="kbd">\*</kbd> opens every folder beside the focused row: call
  `toggle(folder, true)` on each folder in the same group.

---

Source: https://keyrove.pages.dev/docs/examples/roving-tabindex

# Roving tabindex

> Give a group one tab stop, initialize it after rendering, and keep it with keyboard, pointer and programmatic focus.

With the default bindings, <kbd class="kbd">Tab</kbd> visits every item with `tabindex="0"`. Roving
tabindex gives the group one tab stop; the navigation keys move between items.

- Put `data-keyrove-roving-tabindex` on every item, or pass
  `{ rovingTabindex: true }` for the group.
- Give one navigable item `tabindex="0"` and the rest `tabindex="-1"`.
  Choose the first item or the widget's selected item, excluding skipped and
  disabled items.
- On a move from a roving item, keyrove sets the previous item to `-1` and the
  destination to `0`.
- Each nested root keeps its own stop. A move onto a nested root's item moves
  that root's stop to it and leaves the outer group's stop in place.

Arrow to an item, then <kbd class="kbd">Tab</kbd> away and <kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd> back. Focus returns to that item.

```html
<ul id="statuses">
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="0">Backlog</li>
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">To do</li>
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">Blocked</li>
  <!-- … -->
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">Archived</li>
</ul>
```

## Setting the initial tab stop

`keyRove` does not initialize the group's tab stop. Set it in the markup or
call `initRovingTabindex` after rendering:

```ts
import { initRovingTabindex } from '@mixedrays/keyrove';

initRovingTabindex(list);
```

An existing navigable roving item with `tabindex="0"` keeps the stop. If there
are several, the first in DOM order wins. If there are none, the first roving
item that is neither skipped nor disabled gets `0`. All other roving items
get `-1`.

Call the helper after a render that may replace items. It preserves a valid
stop or repairs a missing one. Nested roots keep their own stops; initialize
each root separately.

Where the item that should start with the stop is known to your code but not
marked in the DOM, such as a tab list's active tab, name it in `initial`:

```ts
initRovingTabindex(tabs, {
  initial: tabs.querySelector('[aria-selected="true"]'),
});
```

A valid `initial` overrides the existing stop. Use it for first setup or an
intentional selection change, and omit it during routine render updates.
A null, skipped, disabled or non-roving item is ignored.

If no item has `tabindex="0"`, <kbd class="kbd">Tab</kbd> cannot enter through the items. Keep one
stop whenever the group has a navigable roving item.

## Focus that keyrove did not move

Attach `followFocus` to `focusin` to update the stop after a click, a call to
`element.focus()`, or <kbd class="kbd">Tab</kbd> entering a control inside an item. It also handles
entry from outside the group, where keyrove has no previous item to take the
stop from:

```ts
import { followFocus, keyRove } from '@mixedrays/keyrove';

list.addEventListener('keydown', (e) => keyRove(e));
list.addEventListener('focusin', (e) => followFocus(e));
```

It reads the group the way `keyRove` does, so it leaves a nested group's stop
alone, gives no stop to a skipped item, and takes the same options object
where the group is described in JavaScript. The
[listbox](/docs/examples/listbox) uses it for clicks.

The [complete roving setup](/docs/installation#complete-roving-setup) wires
initialization, navigation, focus tracking and typeahead to one
configuration object.

## Choosing between the two

Choose the tab order that fits the widget:

|                            | Plain tab stops             | Roving tabindex                            |
| -------------------------- | --------------------------- | ------------------------------------------ |
| <kbd class="kbd">Tab</kbd> | Steps through every item    | Steps past the whole group                 |
| Bound keys                 | Move between items          | Move between items                         |
| Cost to the page           | One stop per item           | One stop per group                         |
| Setup                      | `tabindex="0"` on each item | One `0`, the rest `-1`, plus the attribute |

Use plain tab stops when each item should be a separate destination in the
page's tab order. Use roving tabindex for a composite control such as a
[listbox](/docs/examples/listbox), [tree](/docs/examples/tree-view), grid or
tab list. See the
[ARIA keyboard practices](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
for widget-specific guidance. With roving tabindex,
[<kbd class="kbd">Tab</kbd> can leave a nested group](/docs/examples/nested-roots#getting-back-out)
without an extra exit handler.

---

Source: https://keyrove.pages.dev/docs/examples/skipped-items

# Skipped items

> Skip headings and unavailable items during keyboard navigation while preserving grid positions, or exclude disabled elements entirely.

Add `data-keyrove-skip` to pass over an item during navigation while keeping
its position in the sequence. Try the arrows here: focus skips the headings.

```html
<ul id="files">
  <li data-keyrove-item data-keyrove-skip>Recent</li>
  <li data-keyrove-item tabindex="0">quarterly-report.pdf</li>
  <li data-keyrove-item tabindex="0">budget-v3-final-FINAL.xlsx</li>
  <li data-keyrove-item data-keyrove-skip>Shared with me</li>
  <li data-keyrove-item tabindex="0">roadmap.md</li>
  <!-- … -->
  <li data-keyrove-item tabindex="0">pension-fund.xls</li>
</ul>
```

The headings keep `data-keyrove-item` and add `data-keyrove-skip`. Removing
`data-keyrove-item` also excludes a heading from a list, but in a grid it
shifts the positions of later cells. A skipped cell keeps its slot.

Skipping does not remove an item's native <kbd class="kbd">Tab</kbd> stop; set its tabindex as
needed. An explicit `focusKeys` mapping can still reach a skipped target;
see [configuration differences](/docs/attributes-and-options#configuration-differences).

## Disabled elements

Anything carrying the `disabled` attribute is excluded automatically, with no
`data-keyrove-skip` needed:

```html
<button data-keyrove-item tabindex="0">Rename</button>
<button data-keyrove-item disabled>Delete</button>
<button data-keyrove-item tabindex="0">Duplicate</button>
```

Excluded items leave the sequence, so in a grid a disabled cell shifts every
later cell. To keep its slot, use `aria-disabled="true"` with
`data-keyrove-skip` instead. Use the same pair for a `<li>` or `<div>`, since
native `disabled` behavior applies only to supported form controls. keyrove
does not write ARIA states or prevent your activation handlers from running.

## <kbd class="kbd">Home</kbd> and <kbd class="kbd">End</kbd>

<kbd class="kbd">Home</kbd> and <kbd class="kbd">End</kbd> respect skipping too:
they land on the first and last _navigable_ items, not on a leading heading or a
trailing separator.

If every item is skipped, no move lands anywhere. Arrows pressed from outside
the group keep their browser default, and keys pressed from a focused item are
consumed without moving. Typeahead and roving initialization behave the same
way. See [the edge rules](/docs/api#edges-and-looping).

---

Source: https://keyrove.pages.dev/docs/examples/nested-roots

# Nested roots

> Nest keyboard navigation groups, each with its own keys, columns and page size, and give users a way to enter the inner group and return to the outer one.

Put `data-keyrove-root` on an inner group to give it its own keys, columns
and page size.

In this menu, <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move between actions. <kbd class="kbd">↑</kbd> from _Reply_ enters the
reaction row, where <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd> move between reactions. <kbd class="kbd">Escape</kbd> returns focus to
the menu.

```html
<ul id="message-actions">
  <li
    data-keyrove-root
    data-keyrove-next-key="ArrowRight"
    data-keyrove-prev-key="ArrowLeft"
    data-keyrove-exit-key="Escape"
  >
    <button data-keyrove-item tabindex="0">👍</button>
    <button data-keyrove-item tabindex="0">❤️</button>
    <!-- … -->
    <button data-keyrove-item tabindex="0">🎉</button>
  </li>
  <li data-keyrove-item tabindex="0">Reply</li>
  <li data-keyrove-item tabindex="0">Reply in thread</li>
  <li data-keyrove-item tabindex="0">Copy link</li>
  <!-- … -->
  <li data-keyrove-item tabindex="0">Delete message</li>
</ul>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

document
  .querySelector('#message-actions')
  .addEventListener('keydown', (e) => keyRove(e));
```

The outer list has one listener. Events bubble to it, and keyrove finds the
root from the event target. The outer list needs no root attribute because it
is the listener's element. If you move the listener to a panel or `document`,
mark the outer list with `data-keyrove-root` too.

## The nearest root wins

Root attributes are read off the group focus is currently in, and nothing is
inherited across the boundary:

```html
<div id="settings" data-keyrove-root data-keyrove-page-length="5">
  <div data-keyrove-item tabindex="0">Appearance</div>

  <!-- A swatch grid: 4 columns and 2-row pages apply in here only. -->
  <div data-keyrove-root data-keyrove-cols="4" data-keyrove-page-length="2">
    <button data-keyrove-item tabindex="0">Indigo</button>
    <button data-keyrove-item tabindex="0">Teal</button>
  </div>

  <div data-keyrove-item tabindex="0">Notifications</div>
</div>
```

<kbd class="kbd">PageDown</kbd> moves five rows in the settings list and two
grid rows in the swatch grid; <kbd class="kbd">←</kbd> <kbd class="kbd">→</kbd>
move a cell inside the grid and nothing outside it. <kbd class="kbd">Home</kbd>
and <kbd class="kbd">End</kbd> follow the same rule: inside the grid they land
on the ends of its focused row, never on the list's.

### The outer group still sees the inner items

`data-keyrove-item` is matched anywhere below the root, nested groups included,
so the outer group's order runs straight _through_ the inner one. In the demo,
<kbd class="kbd">↑</kbd> from _Reply_ lands on the last reaction rather than
skipping the row.

This lets outer navigation enter the inner group. To keep the groups'
attribute-selected item sequences separate, place them in sibling roots.

## Getting back out

Inside a nested root, only that root's movement bindings apply. Unbound keys
do not fall through to the outer group. In the reaction row, <kbd class="kbd">↓</kbd> is unhandled
(gray in the readout, _left to the browser_); <kbd class="kbd">←</kbd> at the first reaction is
consumed without moving (amber, _prev · moved nothing_).

Provide a way to leave the inner group:

1. **<kbd class="kbd">Tab</kbd>.** keyrove never binds it, so the browser's
   focus order is always a way out. With
   [roving tabindex](/docs/examples/roving-tabindex) on each group,
   <kbd class="kbd">Tab</kbd> moves group to group and
   <kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd> back. No code.
2. **An exit key.** The demo binds <kbd class="kbd">Escape</kbd> on the
   reaction row:

   ```html
   <li
     data-keyrove-root
     data-keyrove-next-key="ArrowRight"
     data-keyrove-prev-key="ArrowLeft"
     data-keyrove-exit-key="Escape"
   >
     <button data-keyrove-item tabindex="0">👍</button>
     …
   </li>
   ```

   Exit focuses the outer item containing the root, or the nearest eligible
   item after it, then before it. Here, the reaction row has no containing
   item, so <kbd class="kbd">Escape</kbd> focuses _Reply_. Each root finds its destination from the
   DOM, so several reaction rows can use the same binding. If there is no
   destination, <kbd class="kbd">Escape</kbd> remains unhandled.

3. **A [focus key](/docs/examples/focus-keys) on an item of the outer group.**
   `data-keyrove-focus-key` works from anywhere under the listener, nested
   roots included. Use it to return to a fixed destination.

## Getting in

Outer arrow navigation can reach items inside nested roots, as in the reaction
row above. With roving tabindex, such a move updates the nested root's stop and
leaves the outer group's stop in place. When an outer item contains its own
group, bind an enter key on the outer root to focus that group's items:

```html
<ul id="messages" data-keyrove-enter-key="Enter">
  <li data-keyrove-item tabindex="0">
    Build failed
    <div data-keyrove-root data-keyrove-exit-key="Escape">
      <button data-keyrove-item tabindex="0">Retry</button>
      <button data-keyrove-item tabindex="0">View logs</button>
    </div>
  </li>
</ul>
```

<kbd class="kbd">Enter</kbd> focuses the first nested root's navigable roving tab stop, or its first
navigable item. <kbd class="kbd">Escape</kbd> returns to the containing item. Skipped and disabled
items are excluded.

To remember the last focused button, set up
[roving tabindex](/docs/examples/roving-tabindex) in each group. Enter and exit
preserve the stop in the group being left. The markup above uses ordinary tab
stops, so <kbd class="kbd">Enter</kbd> starts at _Retry_ each time.

Neither action has a default binding. You can also use
`keys: { enter: 'Enter', exit: 'Escape' }`. When no destination is found, the
key remains available to the browser and your handlers. See the
[API reference](/docs/api#exit-and-enter) for target and focus rules.

## Nesting, or two roots side by side

Use nested roots when outer navigation should reach the inner items. For
independent groups, place sibling roots under a shared listener. See
[several groups, one listener](/docs/installation#several-groups-one-listener).

---

Source: https://keyrove.pages.dev/docs/examples/focus-keys

# Focus keys

> Assign keyboard shortcuts that focus an item or panel from anywhere under the listener, across groups and even from inside a text field.

Set `data-keyrove-focus-key` on an element to focus it with a shortcut from
anywhere under the listener.

<kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Shift</kbd>+<kbd class="kbd">1</kbd>, <kbd class="kbd">2</kbd> or <kbd class="kbd">3</kbd> focuses a panel in this demo. Try a shortcut from the text
area: focus keys with <kbd class="kbd">Ctrl</kbd>, <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> also work inside editable fields.

```html
<div id="editor-panes">
  <section data-keyrove-focus-key="ctrl+shift+Digit1" tabindex="0">
    Explorer
  </section>
  <section data-keyrove-focus-key="ctrl+shift+Digit2" tabindex="0">
    Editor
    <textarea
      rows="3"
      placeholder="Type here — the chords still reach out"
    ></textarea>
  </section>
  <section data-keyrove-focus-key="ctrl+shift+Digit3" tabindex="0">
    Terminal
  </section>
</div>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

document
  .querySelector('#editor-panes')
  .addEventListener('keydown', (e) => keyRove(e));
```

The panels are not navigation items, so arrows do not move between them.
Each panel has its own [combo](/docs/api#combos). A bare code also works:
`data-keyrove-focus-key="KeyE"` focuses an element with <kbd class="kbd">E</kbd> outside editable
fields.

The move reports `action: 'focus'` to `onMove` and in the
[return value](/docs/api#return-value).

## As far as the listener hears

keyrove looks for focus keys on every element under the listener's element,
not just in the nearest root, so where you attach the listener is the only
scope control:

- On a panel, the keys work inside that panel.
- On `document`, they work page-wide.
- From inside a [nested root](/docs/examples/nested-roots), a focus key
  outside it still fires. Focus keys are the third way out of a nested group,
  after <kbd class="kbd">Tab</kbd> and a key of your own.

## A key and an order

An element can have both `data-keyrove-item` and a focus key. This palette
supports arrow navigation and direct shortcuts to tools.

```html
<div
  id="tools"
  role="toolbar"
  aria-orientation="vertical"
  aria-label="Drawing tools"
>
  <button
    data-keyrove-item
    data-keyrove-roving-tabindex
    data-keyrove-focus-key="KeyV"
    aria-keyshortcuts="V"
    tabindex="0"
  >
    Move
  </button>
  <button
    data-keyrove-item
    data-keyrove-roving-tabindex
    data-keyrove-focus-key="KeyF"
    aria-keyshortcuts="F"
    tabindex="-1"
  >
    Frame
  </button>
  <!-- … -->
  <button
    data-keyrove-item
    data-keyrove-roving-tabindex
    data-keyrove-focus-key="KeyH"
    aria-keyshortcuts="H"
    tabindex="-1"
  >
    Hand
  </button>
</div>
```

```ts
document.querySelector('#tools').addEventListener('keydown', (e) => keyRove(e));
```

Press <kbd class="kbd">P</kbd> for the pen, then <kbd class="kbd">↓</kbd>: the
arrow steps on from wherever the key landed, because the pen is a stop in the
same order the arrows walk. The readout tells the two apart, `focus` for the jump
and `next` for the step. Then <kbd class="kbd">Tab</kbd> out of the palette and
<kbd class="kbd">Shift</kbd>+<kbd class="kbd">Tab</kbd> back: focus returns to
the tool you last reached, whichever way you reached it, because the
[roving tab stop](/docs/examples/roving-tabindex) follows a jump as it follows
an arrow.

Focus keys use the bindings you choose: <kbd class="kbd">V</kbd> for Move, <kbd class="kbd">O</kbd> for Ellipse, <kbd class="kbd">I</kbd> for
Eyedropper. [Typeahead](/docs/examples/typeahead) instead matches labels.

Each tool also has `aria-keyshortcuts`. The demo uses it to display the shortcut
beside the label; see [telling users about it](#telling-users-about-it).

A focus key only moves focus. To select or activate the tool, add your own
logic, for example in `onMove` using the destination `to`.

## Item or not

A focus key needs no `data-keyrove-item`, and whether its element has one
decides what else reaches it:

- **An item**, like a tool in the palette, stays in its group's order, so the
  arrows reach it too, and the key is a shortcut to a place they already go.
  The jump is a move in that group: `from` is the item focus left, or `null`
  from outside the group, and a
  [roving tab stop](/docs/examples/roving-tabindex) moves when focus leaves a
  roving item. Attach `followFocus` to `focusin` to update the stop when the
  shortcut enters from outside the group.
- **Any other element**, like the panels, is reached by its key alone. No arrow
  lands on it. A jump to it reports `from: null` and moves no group tab stop.
  If focus is already inside it, `from` is that element and `to` is `null`.

Either way, pressing the key while focus is already inside its element is a
consumed no-op: the key is claimed, and focus stays where it is. The
[API reference](/docs/api#focus-keys) has the exact rules.

A panel with a list inside is best made that list's root: put
`data-keyrove-root` on the panel itself. The jump leaves focus on the panel,
and an arrow pressed there then enters the panel's own list. Without the root,
the arrow belongs to the group around the panels and lands on the first item
under the listener, whichever panel that is in.

```html
<section
  data-keyrove-root
  data-keyrove-focus-key="ctrl+shift+Digit1"
  tabindex="-1"
>
  <ul>
    <li data-keyrove-item tabindex="-1">index.ts</li>
    <li data-keyrove-item tabindex="-1">README.md</li>
  </ul>
</section>
```

The panel's `tabindex="-1"` is what lets it take focus while keeping it out of
the <kbd class="kbd">Tab</kbd> order. Without it, or on any element that cannot
take focus, the key is still claimed, but focus stays where it was and
`onMove` does not fire.

## From inside a text field

Movement bindings leave [editable targets](/docs/examples/editable-targets)
their editing keys. Focus shortcuts are the exception:

- A combo holding <kbd class="kbd">Ctrl</kbd>, <kbd class="kbd">Alt</kbd> or
  <kbd class="kbd">Meta</kbd> fires from inside a field.
- A bare combo, or one holding only <kbd class="kbd">Shift</kbd>, does not.

In the demo, `ctrl+shift+Digit1` reaches out of the text area; a bare `Digit1`
would type a "1" there and focus the panel from everywhere else.

Choose shortcuts that do not conflict with editing commands or text input.
For example, <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">B</kbd> can mean bold; <kbd class="kbd">Alt</kbd>+letter can type accented characters on
macOS; and Windows can report <kbd class="kbd">AltGr</kbd> as <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Alt</kbd>. A `ctrl+alt+` focus shortcut
can therefore fire during text entry. No focus key runs while `isComposing`
is true.

## Precedence and ties

Focus keys take precedence over explicit movement bindings and defaults.
For example, an element's `Home` focus key overrides the usual <kbd class="kbd">Home</kbd> action.

When two elements declare the same combo, the first in DOM order wins.
The attribute scan excludes skipped and disabled targets. An explicit
`focusKeys` map replaces that scan and bypasses skip checks, but still excludes
disabled targets; see
[configuration differences](/docs/attributes-and-options#configuration-differences).

If a target is excluded, another binding may handle the key. If none matches,
the browser keeps it. Consider the listener's scope when assigning shortcuts:
a bare letter on a document listener applies across the page.

## Telling users about it

Add
[`aria-keyshortcuts`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts)
to expose a shortcut to assistive technology. keyrove does not set it for you.
ARIA uses key names, while keyrove uses physical codes:
`data-keyrove-focus-key="ctrl+shift+KeyE"` pairs with
`aria-keyshortcuts="Control+Shift+E"`.

---

Source: https://keyrove.pages.dev/docs/examples/typeahead

# Typeahead

> Add typeahead to a list or menu so typing a label focuses its item, with prefix matching, repeated-character cycling and accent handling.

Create a typeahead handler to focus items by typing their labels. In this
list, <kbd class="kbd">S</kbd> focuses _Spanish_ and <kbd class="kbd">W</kbd> immediately after it focuses _Swedish_.
After a 500 ms pause, the next character starts a new prefix.

```html
<ul id="languages">
  <li data-keyrove-item tabindex="0">Arabic</li>
  <li data-keyrove-item tabindex="0">Bengali</li>
  <li data-keyrove-item tabindex="0">Chinese</li>
  <!-- … -->
  <li data-keyrove-item tabindex="0">Turkish</li>
</ul>
```

```ts
import { createTypeahead, keyRove } from '@mixedrays/keyrove';

const typeahead = createTypeahead();

document
  .querySelector('#languages')
  .addEventListener('keydown', (e) => keyRove(e) || typeahead(e));
```

Call `keyRove` first so navigation bindings take precedence. It returns `null`
for an unhandled key, letting `typeahead` process it. For example, a `KeyJ`
navigation binding moves focus instead of adding <kbd class="kbd">J</kbd> to the prefix.

## Why a factory

The returned handler stores the prefix and the time of the last character.
Create it once per listener, outside the keydown callback. It checks the time
on each press, so there is no timer to clean up. Set `resetMs` to change the
pause that clears the prefix:

```ts
const typeahead = createTypeahead({ resetMs: 800 });
```

## Cycling repeated characters

Prefix matching is the default: pressing <kbd class="kbd">S</kbd> twice looks
for a label starting with `ss`, and every prefix matches from the top of the
list. A menu can instead cycle through the items sharing one initial character,
the way a native `<select>` does:

```ts
const typeahead = createTypeahead({ matchMode: 'cycle' });
```

With that mode, a single character moves focus to the next item after the
focused one that begins with it, wrapping after the last. Pressing it again
moves on rather than growing the buffer, however slowly it is pressed, so
repeated <kbd class="kbd">S</kbd> presses alternate between _Spanish_ and
_Swedish_. A different character typed before the reset still refines the
prefix, so <kbd class="kbd">S</kbd> <kbd class="kbd">W</kbd> matches _Swedish_.
The one thing the mode gives up is a label that opens with a doubled letter:
<kbd class="kbd">A</kbd> <kbd class="kbd">A</kbd> cycles the _A_ items and
never looks for "aa".

## What counts as typing

Bindings match the physical key, `e.code`. Typeahead reads `e.key`, the
character the press produced in the user's layout, so "é" and "ß" work where
the keyboard has them. A press joins the buffer when it is typing and nothing
else:

- a single character, with none of <kbd class="kbd">Ctrl</kbd>,
  <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> held.
  <kbd class="kbd">Shift</kbd> is allowed; it is how capitals are typed, and
  matching ignores case anyway;
- not inside an [editable target](/docs/examples/editable-targets), so a field
  inside an item keeps its letters;
- a space only once the buffer holds a character, so the spacebar keeps
  scrolling the page and activating buttons while "do n" still reaches
  _Do not disturb_ below.

Matching is by prefix. A character that matches nothing is left to the
browser but still joins the buffer, so a mistyped prefix goes quiet until the
reset clears it rather than jumping somewhere unexpected. Items carrying
`data-keyrove-skip` or `disabled` are never matched.

## When the text is not the label

The label is the item's text, trimmed and with runs of whitespace collapsed.
When the text starts with something nobody types, an emoji, an icon's fallback
text, a code, `data-keyrove-typeahead` names the label instead:

```html
<ul id="presence">
  <li data-keyrove-item data-keyrove-typeahead="Available" tabindex="0">
    🟢 Available
  </li>
  <li data-keyrove-item data-keyrove-typeahead="Away" tabindex="0">🟡 Away</li>
  <li data-keyrove-item data-keyrove-typeahead="Do not disturb" tabindex="0">
    🔴 Do not disturb
  </li>
  <li data-keyrove-item data-keyrove-typeahead="Appear offline" tabindex="0">
    ⚫ Appear offline
  </li>
</ul>
```

<kbd class="kbd">A</kbd> is _Available_, <kbd class="kbd">A</kbd>
<kbd class="kbd">W</kbd> is _Away_, <kbd class="kbd">D</kbd> is
_Do not disturb_. The attribute is the whole label rather than a prefix added
to the text, and an empty one falls back to the text, so a template can set it
conditionally.

## Accented labels

Accents are ignored on both sides: <kbd class="kbd">E</kbd> reaches _Émilie_,
<kbd class="kbd">A</kbd> reaches _Ángel_, and on a keyboard that can type it,
<kbd class="kbd">É</kbd> reaches a plain _Emilie_ too. Each letter is compared
with its marks taken off, whether the label comes from the text, the attribute
or a `label` function, so no label needs folding by hand. A letter that is not
a base letter plus a mark, such as _ø_, _ł_ or _ß_, is matched as itself.

Where an accent is what tells two items apart, turn the folding off:

```ts
const typeahead = createTypeahead({ foldDiacritics: false });
```

## What it reports

The handler returns `null` when it left the key alone and
`{ action: 'typeahead', from, to }` when it consumed it, with `to: null` when
the match is already focused or cannot receive focus. `onMove` fires only
after a successful focus move.

Type "swez" quickly to see each result in the readout:

- <kbd class="kbd">S</kbd> and <kbd class="kbd">W</kbd> are indigo: focus moves to _Spanish_, then _Swedish_.
- <kbd class="kbd">E</kbd> is amber, _typeahead · moved nothing_: "swe" still matches the focused item, so `to` is `null`.
- <kbd class="kbd">Z</kbd> is gray, _left to the browser_: "swez" matches nothing, so the handler returns `null`.

The unmatched character stays in the buffer. Pause for 500 ms to start again.

Both handlers can feed one follow-focus callback, a preview pane for one:

```ts
const onMove = ({ to }) => showPreview(to);

const typeahead = createTypeahead({ onMove });

list.addEventListener('keydown', (e) => keyRove(e, { onMove }) || typeahead(e));
```

The roving tab stop moves with the match, as it does for an arrow move.

## Several groups, one handler

The buffer clears when the next typing key resolves to a different root.
One handler can therefore serve several groups under a delegated listener
without sharing prefixes between them. See
[several groups, one listener](/docs/installation#several-groups-one-listener).

---

Source: https://keyrove.pages.dev/docs/examples/editable-targets

# Editable targets

> Mix keyboard navigation with text fields, selects and sliders. Editable controls keep their native keys while the arrows move between the rows around them.

Movement bindings leave editable fields their native keys. Arrows can move a
caret or change a value, and letter bindings do not capture typed text. Modified
focus shortcuts are the [exception](#the-one-exception).

Arrow between the demo's rows, then <kbd class="kbd">Tab</kbd> into a control. Text fields keep their
editing behavior, _Font size_ keeps its slider keys, and <kbd class="kbd">↓</kbd> on the checkbox
moves to the next row. The readout shows navigation in indigo and keys left to
the browser in gray.

```html
<ul id="settings">
  <li data-keyrove-item tabindex="0">
    <label>
      <input type="checkbox" checked />
      Email notifications
    </label>
  </li>
  <li data-keyrove-item tabindex="0">
    <label>
      Display name
      <input type="text" value="Ada" />
    </label>
  </li>
  <li data-keyrove-item tabindex="0">
    <label>
      Font size
      <input type="range" min="12" max="24" value="16" />
    </label>
  </li>
  <li data-keyrove-item tabindex="0">
    <label>
      <input type="checkbox" />
      Weekly digest
    </label>
  </li>
  <li data-keyrove-item tabindex="0">
    <label>
      Signature
      <textarea rows="2">Sent from my keyboard</textarea>
    </label>
  </li>
</ul>
```

```ts
import { keyRove } from '@mixedrays/keyrove';

document
  .querySelector('#settings')
  .addEventListener('keydown', (e) => keyRove(e));
```

No extra configuration is needed. A row remains the current item while focus
is inside one of its controls. When navigation resumes, it starts from that row.

## Which elements are editable

The test is on the event's target and its ancestors:

- a `textarea` or a `select`;
- a `[contenteditable]` element and everything inside it, except a
  `contenteditable="false"` island, which opts back out;
- an `input` of any type other than `button`, `checkbox`, `color`, `file`,
  `image`, `reset` and `submit`.

The input list is drawn by what the bound keys do natively. Arrows move a
caret in a text field, step a `number`, slide a `range` and move between
`radio` buttons; on a checkbox or a button they do nothing, so navigating from
one takes nothing away. That is why <kbd class="kbd">↓</kbd> on
_Email notifications_ moves rows while <kbd class="kbd">↓</kbd> on _Font size_
nudges the slider.

## By target, not by key

The target determines whether movement keys are handled. In a text field,
`ctrl+ArrowRight` still moves by word and `KeyJ` still types "j", even when
those combos are bound to navigation. `keyRove` returns `null`, so any handler
chained after it also receives the event.

## The one exception

A [focus key](/docs/examples/focus-keys) with <kbd class="kbd">Ctrl</kbd>, <kbd class="kbd">Alt</kbd> or <kbd class="kbd">Meta</kbd> can move focus
from an editable field. Bare keys and <kbd class="kbd">Shift</kbd>-only combinations remain available
for typing. Choose shortcuts carefully: some modifiers also produce text,
including <kbd class="kbd">AltGr</kbd> reported as <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Alt</kbd>.

[Typeahead](/docs/examples/typeahead) never captures typing inside a field.

## While an input method composes

While `isComposing` is true, keyrove leaves every key to the input method,
including modified focus shortcuts. This lets users navigate candidates and
finish entering text.

## Rows as tab stops

Each row here carries `tabindex="0"` so it can be focused apart from its
control, which is what lets a row be the position before
<kbd class="kbd">Tab</kbd> reaches the control inside. It also doubles the tab
stops. Put [roving tabindex](/docs/examples/roving-tabindex) on the rows and
the list costs one stop, with the controls keeping theirs. Or make the controls
the items, `<input data-keyrove-item type="checkbox">`, and the rule reads the
same way round: the checkboxes navigate, the text fields do not.

---

Source: https://keyrove.pages.dev/docs/examples/javascript-options

# Options in JavaScript

> Add keyboard navigation to markup you cannot change, such as a menu from a component library or CMS, with JavaScript options that select items by role.

Use options to navigate markup from a component library, CMS or other code
you cannot change. This menu has no `data-keyrove-*` attributes; its options
select items by their existing role.

```html
<div id="share" role="menu" aria-label="Share">
  <button type="button" role="menuitem" tabindex="0">Copy link</button>
  <button type="button" role="menuitem" tabindex="-1">Email a copy</button>
  <button type="button" role="menuitem" tabindex="-1" disabled>
    Export as PDF
  </button>
  <button type="button" role="menuitem" tabindex="-1">Post to Slack</button>
  <button type="button" role="menuitem" tabindex="-1">Open in Figma</button>
</div>
```

```ts
import { createTypeahead, keyRove } from '@mixedrays/keyrove';

const config = {
  items: '[role="menuitem"]',
  loop: true,
  rovingTabindex: true,
};

const typeahead = createTypeahead(config);

document
  .querySelector('#share')
  .addEventListener('keydown', (e) => keyRove(e, config) || typeahead(e));
```

<kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> move between items and wrap at the ends. Typing finds an entry, and
<kbd class="kbd">Tab</kbd> leaves the menu. The options configure navigation; the markup supplies
roles, an initial tab stop and the `disabled` attribute on _Export as PDF_.

## What is coming from where

Options override attributes one setting at a time. For example,
`keyRove(e, { loop: true })` enables looping while still finding items from
markup. See [attributes and options](/docs/attributes-and-options) for
replacement rules and the [API reference](/docs/api#options) for every field.

## One object, both handlers

Pass the same `items`, `root`, `skip` and `rovingTabindex` settings to both
handlers. In the demo, typing <kbd class="kbd">P</kbd> reaches _Post to Slack_ through the same
selector the arrows use.

Typeahead ignores movement settings such as keys, columns and looping. Use its
[`label`](/docs/api#createtypeahead-options) option when an item's text is not
its search label. Create the handler once per listener.

## Items, by selector or by hand

`items` takes a selector, run inside the group's root on each keypress, or a
function returning the elements:

```ts
keyRove(e, { items: '[role="menuitem"]' });
keyRove(e, { items: (root) => [...root.querySelectorAll('.row')].reverse() });
```

Either way the elements are the group's sequence in the order given, and
`disabled` ones are left out — the same rule the attribute reading follows,
because it is applied to the items rather than to the reading that found them.
A `skip` test passes items over while keeping them in the sequence, which is
what a grid needs: a skipped cell holds its column.

```ts
keyRove(e, { items: '.cell', skip: '.cell-empty', cols: 4 });
```

## Where this belongs

Use options when you cannot edit the markup or need a computed setting:
`keyRove(e, { items: '.cell', cols: columnsNow() })` reads the column count on
each call. For CSS grids, `cols: 'auto'` or `data-keyrove-cols="auto"` reads it
from the layout; see [responsive grid](/docs/examples/responsive-grid).

---

Source: https://keyrove.pages.dev/docs/examples/listbox

# Listbox

> Build a single-select listbox with keyboard navigation, typeahead, roving tabindex and explicit selection, while your widget supplies the ARIA roles.

This single-select listbox combines navigation, roving tabindex and typeahead.
The widget supplies ARIA roles, selection and click handling.

<kbd class="kbd">Tab</kbd> into it and arrow around, type a first letter to
jump, then press <kbd class="kbd">Enter</kbd> to pick. <kbd class="kbd">Space</kbd> also selects
when typeahead is inactive; wait 500 ms after typing to use it. Clicking picks
too. <kbd class="kbd">Tab</kbd> away and back, and focus returns to where you
left it.

```html
<ul id="assignee" role="listbox" aria-label="Assignee">
  <li
    role="option"
    aria-selected="true"
    data-keyrove-item
    data-keyrove-roving-tabindex
    tabindex="0"
  >
    Ada Lovelace
  </li>
  <li
    role="option"
    aria-selected="false"
    data-keyrove-item
    data-keyrove-roving-tabindex
    tabindex="-1"
  >
    Alan Turing
  </li>
  <!-- … -->
  <li
    role="option"
    aria-selected="false"
    data-keyrove-item
    data-keyrove-roving-tabindex
    tabindex="-1"
  >
    Barbara Liskov
  </li>
</ul>
```

```ts
import {
  createTypeahead,
  followFocus,
  keyRove,
  matchesCombo,
} from '@mixedrays/keyrove';

const listbox = document.querySelector('#assignee');
const typeahead = createTypeahead();

const select = (option) => {
  for (const each of listbox.querySelectorAll('[role="option"]')) {
    each.setAttribute('aria-selected', String(each === option));
  }
};

const pick = (e) => {
  if (!matchesCombo(e, 'Space, Enter')) return null;

  const option = e.target.closest('[role="option"]');
  if (!option) return null;

  e.preventDefault();
  select(option);

  return option;
};

listbox.addEventListener('keydown', (e) => {
  keyRove(e) || typeahead(e) || pick(e);
});

listbox.addEventListener('focusin', (e) => followFocus(e));

listbox.addEventListener('click', (e) => {
  const option = e.target.closest('[role="option"]');
  if (option) select(option);
});
```

The readout tells selection from focus movement by its verb:
<kbd class="kbd">↓</kbd> from _Ada Lovelace_ reads _next → Alan Turing_, and
<kbd class="kbd">Enter</kbd> then reads _selected → Alan Turing_.

## The pieces

- **The markup.** `role="listbox"` on the list, `role="option"` and
  `aria-selected` on every item, `aria-label` on the widget. This is what makes
  it a listbox to assistive technology, and keyrove neither reads nor writes
  any of it: roles and states are
  [left to you](/docs/introduction#what-it-leaves-to-you) because what they
  should say depends on the widget.
- **Navigation.** `data-keyrove-item` on every option and `keyRove` first in
  the chain. The arrows, <kbd class="kbd">Home</kbd>, <kbd class="kbd">End</kbd>
  and the page keys come with the [basic list](/docs/examples/basic), and they
  are the keys the
  [APG listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)
  asks for. A listbox does not wrap, so there is no `data-keyrove-loop`.
- **One tab stop.** `data-keyrove-roving-tabindex` on every option,
  `tabindex="0"` on the selected one and `-1` on the rest, so
  <kbd class="kbd">Tab</kbd> treats the whole list as one control.
  [Roving tabindex](/docs/examples/roving-tabindex) is the arrangement the APG
  describes for a composite widget, and keyrove carries the stop from here on.
  Options rendered from data can leave the `tabindex` out and have
  `initRovingTabindex` set the stop from the selection instead:
  `initRovingTabindex(listbox, { initial: listbox.querySelector('[aria-selected="true"]') })`.
- **Typeahead.** `createTypeahead()` second in the chain, after navigation and
  before the widget's own keys, so a letter jumps and a bound key never becomes
  typing. See [typeahead](/docs/examples/typeahead).
- **Picking.** `pick` runs after navigation and typeahead. It uses
  `matchesCombo` for exact <kbd class="kbd">Space</kbd>/<kbd class="kbd">Enter</kbd> matching, so <kbd class="kbd">Ctrl</kbd>+<kbd class="kbd">Space</kbd> remains
  unhandled. It returns `null` for other keys, allowing another handler to
  follow it. Typeahead consumes <kbd class="kbd">Space</kbd> when it extends a matching prefix;
  otherwise, `pick` handles it.
- **The mouse.** `followFocus` updates the roving stop on `focusin`, including
  focus from clicks or code. The click handler then selects the option.

## Selection that follows focus

To select each option as keyboard navigation or typeahead focuses it, pass
`onMove` to both handlers. Replace the keydown chain above with:

```ts
const onMove = ({ to }) => select(to);

const typeahead = createTypeahead({ onMove });

listbox.addEventListener('keydown', (e) => {
  keyRove(e, { onMove }) || typeahead(e);
});
```

Use selection on focus for cheap, reversible changes such as filtering or
sorting. Keep explicit selection when it submits a form or loads a page.
`onMove` covers these handlers' moves; the separate click and `focusin`
listeners still handle pointer selection and the tab stop.

## Variations

- **Multi-select.** Add `aria-multiselectable="true"` to the list and make
  `pick` toggle the focused option's `aria-selected` instead of moving a single
  selection. Nothing about navigation changes.
- **A grid of options.** `data-keyrove-cols` adds
  [grid navigation](/docs/examples/grid). For an ARIA grid, use `role="grid"`
  with rows and cells (`role="row"` and `role="gridcell"`) and implement
  selection for those cells. The key handler chain can stay the same.
- **`aria-activedescendant`.** The other listbox model keeps DOM focus on the
  container and moves a virtual cursor with `aria-activedescendant`. keyrove
  moves real focus, so it does not implement that model; the roving stop above
  is its equivalent.