# keyrove

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

<div class="hero">
<div class="hero-copy">

# Keyboard navigation that behaves itself.

Mark the items and pass `keydown` to `keyRove`. Lists, grids and trees then
move focus the way keyboard users expect, in any framework.

<div class="hero-actions">

[Get started](/docs/introduction) [Examples](/docs/examples)
<span class="hero-install"><code>npm i @mixedrays/keyrove</code><button data-copy-command="npm i @mixedrays/keyrove" aria-label="Copy install command"></button></span>

</div>

<ul class="hero-facts">
<li>~5 kB gzipped</li>
<li>zero deps</li>
<li>any framework</li>
</ul>

</div>
<div class="hero-demo">
<div class="demo-panel">
<div class="demo-panel-header">
<span class="demo-panel-label"><span class="demo-live-indicator" aria-hidden="true"></span>Live · mail folders</span>
<output class="demo-readout" data-demo-readout data-state="blurred"><span aria-hidden="true">click to focus</span></output>
</div>
<ul id="menu" class="hero-folders" aria-label="Mail folders" data-hero-list>
<li data-keyrove-item tabindex="0" data-count="42">Inbox</li>
<li data-keyrove-item tabindex="0" data-count="2">Drafts</li>
<li data-keyrove-item tabindex="0">Sent</li>
<li data-keyrove-item tabindex="0" data-count="9999+">Spam</li>
<li data-keyrove-item tabindex="0">Trash</li>
</ul>

```html copy
<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">Trash</li>
</ul>
```

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

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

</div>
<p class="demo-hint"><kbd class="kbd">↑</kbd> <kbd class="kbd">↓</kbd> move, <kbd class="kbd">Home</kbd> and <kbd class="kbd">End</kbd> jump. <kbd class="kbd">Tab</kbd> still visits each folder.</p>
</div>
</div>

<section class="landing-section" aria-labelledby="use-it-in-your-framework">
<div class="landing-section-copy">
<p class="landing-step">01 / Your stack</p>

## Use it in your framework

The same items, the same handler. `keyRove` accepts native keyboard events
and compatible framework events, including React's synthetic events.
There is no adapter or wrapper component to install.

Start with ordinary attributes. When you want type-checked settings,
[attribute builders](/docs/api#attribute-builders) fit the same templates.

[Framework setup](/docs/installation)

</div>
<div class="landing-section-demo">

<div class="demo-panel demo-panel--code">

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

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

```tsx title="React"
import { keyRove } from '@mixedrays/keyrove';

export const Menu = () => (
  <ul onKeyDown={keyRove}>
    <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>
);
```

```vue title="Vue"
<script setup>
import { keyRove } from '@mixedrays/keyrove';
</script>

<template>
  <ul @keydown="keyRove">
    <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>
</template>
```

```svelte title="Svelte"
<script>
  import { keyRove } from '@mixedrays/keyrove';
</script>

<ul onkeydown={keyRove}>
  <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>
```

</div>

</div>
</section>

<section class="landing-section" aria-labelledby="add-only-the-behavior-you-need">
<div class="landing-section-copy">
<p class="landing-step">02 / Your settings</p>

## Add only the behavior you need

Keep the handler. Change a setting in the markup.

**Looping** wraps from the last item to the first. **Horizontal** changes
the default arrows. **One tab stop** lets Tab enter and leave the group while
the arrows move within it.

Each example adds just one behavior to the list you already know.

</div>
<div class="landing-section-demo">

<div class="pattern-tabs" data-code-tabs>
<div class="pattern-tabs-bar" role="tablist" aria-label="List behavior">
<button role="tab" class="pattern-tab" aria-selected="true">Looping</button>
<button role="tab" class="pattern-tab" aria-selected="false">Horizontal</button>
<button role="tab" class="pattern-tab" aria-selected="false">One tab stop</button>
</div>
<div class="pattern-panel" role="tabpanel">

```html
<ul id="folders-loop" aria-label="Mail folders" data-keyrove-loop>
  <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
import { keyRove } from '@mixedrays/keyrove';

const folders = document.querySelector('#folders-loop');
folders.addEventListener('keydown', (e) => keyRove(e));
```

Press <kbd class="kbd">↓</kbd> on Sent to return to Inbox.

[Looping lists](/docs/examples/looping-lists)

</div>
<div class="pattern-panel" role="tabpanel">

```html
<ul
  id="folders-horizontal"
  aria-label="Mail folders"
  data-keyrove-orientation="horizontal"
>
  <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
import { keyRove } from '@mixedrays/keyrove';

const folders = document.querySelector('#folders-horizontal');
folders.addEventListener('keydown', (e) => keyRove(e));
```

Use <kbd class="kbd">←</kbd> and <kbd class="kbd">→</kbd> to move between folders.

[Horizontal lists](/docs/examples/horizontal-lists)

</div>
<div class="pattern-panel" role="tabpanel">

```html
<ul id="folders-roving" aria-label="Mail folders">
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="0">Inbox</li>
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">Drafts</li>
  <li data-keyrove-item data-keyrove-roving-tabindex tabindex="-1">Sent</li>
</ul>
```

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

const folders = document.querySelector('#folders-roving');
folders.addEventListener('keydown', (e) => keyRove(e));
```

Move with the arrows, then press <kbd class="kbd">Tab</kbd> to leave the group.

[Roving tabindex](/docs/examples/roving-tabindex)

</div>
</div>

</div>
</section>

<section class="landing-section" aria-labelledby="configure-it-where-it-fits">
<div class="landing-section-copy">
<p class="landing-step">03 / Your markup</p>

## Configure it where it fits

Write attributes when you own the markup. Use an item selector when the HTML
comes from a component library or CMS. These two setups navigate identically.

You can mix both: `keyRove(e, { loop: true })` overrides looping while still
reading the items and other settings from their attributes.

[Attributes and options](/docs/attributes-and-options)

</div>
<div class="landing-section-demo">

<div class="demo-panel demo-panel--code">

```html title="Attributes" copy
<ul id="folders">
  <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>
<script type="module">
  import { keyRove } from '@mixedrays/keyrove';

  const folders = document.querySelector('#folders');
  folders.addEventListener('keydown', (e) => keyRove(e));
</script>
```

```html title="Options"
<ul id="folders">
  <li tabindex="0">Inbox</li>
  <li tabindex="0">Drafts</li>
  <li tabindex="0">Sent</li>
</ul>
<script type="module">
  import { keyRove } from '@mixedrays/keyrove';

  const folders = document.querySelector('#folders');
  folders.addEventListener('keydown', (e) => keyRove(e, { items: 'li' }));
</script>
```

</div>

</div>
</section>

<section class="landing-section" aria-labelledby="move-through-a-grid">
<div class="landing-section-copy">
<p class="landing-step">04 / Your layout</p>

## Move through a grid

Give the group a column count and the same handler moves across cells and
between rows. Your CSS still controls the layout.

For a responsive CSS grid, set `data-keyrove-cols="auto"`. keyrove reads the
current tracks on each keypress, so resizing needs no navigation instance
to update.

[Grid navigation](/docs/examples/grid)

</div>
<div class="landing-section-demo">

<div class="pattern-tabs" data-code-tabs>
<div class="pattern-tabs-bar" role="tablist" aria-label="Grid layout">
<button role="tab" class="pattern-tab" aria-selected="true">Fixed columns</button>
<button role="tab" class="pattern-tab" aria-selected="false">Responsive</button>
</div>
<div class="pattern-panel" role="tabpanel">

```html
<div
  id="slots"
  data-keyrove-cols="3"
  style="display: grid; grid-template-columns: repeat(3, 1fr)"
>
  <button data-keyrove-item>09:00</button>
  <button data-keyrove-item>09:30</button>
  <button data-keyrove-item>10:00</button>
  <!-- … -->
  <button data-keyrove-item>13:00</button>
</div>
```

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

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

Use all four arrows. <kbd class="kbd">Home</kbd> and <kbd class="kbd">End</kbd> jump to the ends of a row.

</div>
<div class="pattern-panel" role="tabpanel">

```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 selected
import { keyRove } from '@mixedrays/keyrove';

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

Drag the preview’s lower-right corner to resize it, then try the arrows.

[Responsive grid](/docs/examples/responsive-grid)

</div>
</div>

</div>
</section>

<section class="landing-section" aria-labelledby="combine-behaviors">
<div class="landing-section-copy">
<p class="landing-step">05 / Your interaction</p>

## Combine behaviors

Now put the pieces together: a menu configured with an item selector,
looping, and one tab stop.

Add `createTypeahead` when people should also be able to find an item by
its label. Both handlers share the same group settings; `||` passes a key
to typeahead only when navigation leaves it unhandled.

[JavaScript options](/docs/examples/javascript-options) ·
[Typeahead](/docs/examples/typeahead)

</div>
<div class="landing-section-demo">

```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 selected
import { createTypeahead, keyRove } from '@mixedrays/keyrove';

const config = {
  items: '[role="menuitem"]',
  loop: true,
  rovingTabindex: true,
};
const typeahead = createTypeahead(config);
const menu = document.querySelector('#share');

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

<p class="demo-hint">Type <kbd class="kbd">E</kbd> to focus Email a copy. Arrows skip the disabled item and wrap at the ends.</p>

</div>
</section>

<section class="landing-section" aria-labelledby="build-more-involved-interfaces">
<div class="landing-section-copy">
<p class="landing-step">06 / Your application</p>

## Build more involved interfaces

Give an item a shortcut. Nest groups with their own keys. Or combine focus
navigation with your application's behavior.

The tree is the fullest example: keyrove navigates visible rows and typeahead
finds them by name. Your code opens and closes folders, sets ARIA states,
and decides what activating a file does.

Start with the part you need; the same handler stays underneath.

</div>
<div class="landing-section-demo">

<div class="pattern-tabs" data-code-tabs>
<div class="pattern-tabs-bar" role="tablist" aria-label="Advanced examples">
<button role="tab" class="pattern-tab" aria-selected="true">Shortcuts</button>
<button role="tab" class="pattern-tab" aria-selected="false">Nested groups</button>
<button role="tab" class="pattern-tab" aria-selected="false">Tree</button>
</div>
<div class="pattern-panel" role="tabpanel">

```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="KeyR"
    aria-keyshortcuts="R"
    tabindex="-1"
  >
    Rectangle
  </button>
  <!-- … -->
  <button
    data-keyrove-item
    data-keyrove-roving-tabindex
    data-keyrove-focus-key="KeyT"
    aria-keyshortcuts="T"
    tabindex="-1"
  >
    Text
  </button>
</div>
```

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

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

Press <kbd class="kbd">P</kbd> for Pen, then <kbd class="kbd">↓</kbd> to continue.

[Focus keys](/docs/examples/focus-keys)

</div>
<div class="pattern-panel" role="tabpanel">

```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';

const actions = document.querySelector('#message-actions');
// One listener also serves the nested reaction row.
actions.addEventListener('keydown', (e) => keyRove(e));
```

Use <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd> in the menu. Focus a reaction to try <kbd class="kbd">←</kbd>/<kbd class="kbd">→</kbd>; <kbd class="kbd">Esc</kbd> leaves its group.

[Nested roots](/docs/examples/nested-roots)

</div>
<div class="pattern-panel" role="tabpanel">

```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 selected
import { createTypeahead, keyRove } from '@mixedrays/keyrove';

const tree = document.querySelector('#files');
const config = {
  items: '[role="treeitem"]',
  skip: '[hidden] [role="treeitem"]',
  rovingTabindex: true,
};
const typeahead = createTypeahead(config);

// branch is your application's expand/collapse handler.
// The full tree example includes its implementation.
tree.addEventListener(
  'keydown',
  (e) => keyRove(e, config) || typeahead(e) || branch(e),
);
```

Use <kbd class="kbd">→</kbd> to open a folder and <kbd class="kbd">←</kbd> to close it. Type a file name to jump.

[Full tree implementation](/docs/examples/tree-view#a-full-tree-view)

</div>
</div>

</div>
</section>

## What it leaves to you

keyrove moves focus and nothing else, so it fits whatever widget you are
building.

<div class="split">
<div class="split-col" data-split="keyrove">

### keyrove does

- Finds the next item and focuses it
- Prevents the browser's default only for keys it handles
- Moves the tab stop with focus when roving tabindex is on

</div>
<div class="split-col" data-split="you">

### You do

- Roles, labels and ARIA states
- Selection, and what <kbd class="kbd">Enter</kbd> and <kbd class="kbd">Space</kbd> do
- Focusable items and the first tab stop

</div>
</div>

The [listbox example](/docs/examples/listbox) puts all three together.

<div class="closing">

## Start with a list

Install the package, mark the items, and pass `keydown` to `keyRove`.

<div class="hero-actions">

[Get started](/docs/introduction)
<span class="hero-install"><code>npm i @mixedrays/keyrove</code><button data-copy-command="npm i @mixedrays/keyrove" aria-label="Copy install command"></button></span>

</div>

<div class="next-steps">
<div class="next-step">


### [Installation](/docs/installation)

Setup for vanilla JavaScript, React, Vue and Svelte.

</div>
<div class="next-step">


### [Examples](/docs/examples)

Live demos, from a basic list to a tree view.

</div>
<div class="next-step">


### [API reference](/docs/api)

Every handler, option, key binding and type.

</div>
<div class="next-step">


### [AI prompts](/docs/ai-prompts)

Point a coding assistant at these docs.

</div>
</div>
</div>