---

title: React keymap integration description: Register OpenTUI key bindings and read Keymap state from React

React keymap integration

@opentui/keymap/react puts a pre-created OpenTUI keymap in React context and connects keymap state to React renders.

These bindings require Keymap<Renderable, KeyEvent> from @opentui/keymap/opentui. They do not create or wrap the HTML adapter for browser React apps.

Read React bindings for OpenTUI React setup. Read Keymap hosts for keymap construction.

Exports

The entry point exports these runtime values:

It also exports these types:

Basic setup

/** @jsxImportSource @opentui/react */

import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider, useBindings } from "@opentui/keymap/react"
import { createRoot } from "@opentui/react"

const renderer = await createCliRenderer()
const keymap = createDefaultOpenTuiKeymap(renderer)

function App() {
  useBindings(() => ({
    commands: [
      {
        name: "app.quit",
        run() {
          renderer.destroy()
        },
      },
    ],
    bindings: [{ key: "q", cmd: "app.quit" }],
  }))

  return <text>Press q to quit</text>
}

createRoot(renderer).render(
  <KeymapProvider keymap={keymap}>
    <App />
  </KeymapProvider>,
)

The default OpenTUI factory installs the parser and standard field addons. The provider does not add features and does not own renderer cleanup.

Provider behavior

useKeymap() returns the exact provider value. It throws this error outside a provider:

Keymap not found. Wrap the tree in <KeymapProvider>.

Keep the provider's keymap instance stable for its mounted lifetime. renderer.destroy() also unmounts the React root and runs hook cleanup. See Lifecycle and cleanup.

useBindings()

useBindings(createLayer, deps?) calls useMemo(createLayer, deps) and registers the resulting layer after commit. The default dependency list is [].

Include every prop or state value that changes the returned layer. If reevaluation returns a different layer object, the hook disposes the old layer and registers the new one. An unrelated render keeps the existing layer.

The layer can include Core fields such as priority, bindings, and commands. It can also include fields from installed addons, such as enabled.

React replaces the Core target field with targetRef:

If targetRef.current is null, the hook waits. It checks the ref after each render and registers when the target appears. It also disposes and registers again if the same ref points to another renderable.

Passing targetMode without targetRef throws:

useBindings local bindings need a targetRef

The hook disposes its layer on component unmount. Layer disposal also unsubscribes reactive matchers.

Reactive reads

Both read hooks subscribe to the batched state event. They remove that subscription on unmount.

const activeKeys = useActiveKeys({ includeMetadata: true })
const pendingSequence = usePendingSequence()

useActiveKeys() calls getActiveKeys(options) after each state update. usePendingSequence() calls getPendingSequence() after each state update.

Use these values for key hints, command lists, leader prompts, and status text. The Core keymap API defines both result shapes and state timing.

Store matchers

reactiveMatcherFromStore() accepts a subscribe function and a snapshot reader. Without a predicate, it converts the snapshot to boolean. A predicate can derive the boolean value.

const matcher = reactiveMatcherFromStore(store.subscribe, store.getSnapshot, (mode) => mode === "normal")

useBindings(
  () => ({
    enabled: matcher,
    bindings: [{ key: "x", cmd: "editor.delete-line" }],
  }),
  [matcher],
)

The enabled-field addon subscribes when the layer registers. Disposing the layer calls the store's unsubscribe function.

Test the integration

Use createTestRenderer() for framework rendering and input. Create the OpenTUI keymap from its renderer, then render the provider and drive mockInput.

Use @opentui/keymap/testing for host-independent addon tests. See Testing for renderer cleanup and input helpers.

Complete example: React keymap

Related pages

• React bindings
• Keymap hosts
• Core keymap API
• Testing
• Lifecycle and cleanup