Solid keymap integration

@opentui/keymap/solid puts a pre-created OpenTUI keymap in Solid context and connects keymap state to Solid signals.

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

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

Exports#

The entry point exports these runtime values:

It also exports these types:

Basic setup#

import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider, useBindings } from "@opentui/keymap/solid"
import { render } from "@opentui/solid"

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>
}

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

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 owner lifetime. renderer.destroy() disposes the Solid root and runs hook cleanup. See Lifecycle and cleanup.

useBindings()#

useBindings(createLayer) runs the layer factory in createEffect(). Signals and memos read by the factory become dependencies.

When a dependency changes, Solid disposes the old layer and registers the new result. If the factory reads no reactive value, the layer remains registered until its owner is disposed.

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

Solid replaces the Core target value with a target accessor:

If the target accessor returns null or undefined, the hook waits. A later accessor value causes the effect to register the layer.

Passing targetMode without a target accessor throws:

useBindings local bindings need a target accessor

The effect cleanup disposes the current layer. Layer disposal also unsubscribes reactive matchers.

useKeymapSelector()#

useKeymapSelector(selector) returns Accessor<T>. Call the accessor to read the current value.

const activeKeys = useKeymapSelector((keymap) => keymap.getActiveKeys({ includeMetadata: true }))
const pendingSequence = useKeymapSelector((keymap) => keymap.getPendingSequence())

activeKeys()
pendingSequence()

The hook subscribes to the batched state event on mount. It runs the selector again after each state update and removes the subscription during owner cleanup.

If the host is destroyed during an update, the selector keeps its previous value for the exact host-destroyed error. It throws if no previous value exists or if the previous value is undefined.

Use selectors for key hints, command lists, leader prompts, status text, and other derived views. The Core keymap API defines query results and state timing.

Signal matchers#

reactiveMatcherFromSignal() converts a Solid accessor to ReactiveMatcher. Without a predicate, it converts the accessor value to boolean.

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

The matcher creates a disposable Solid root for each subscription. Disposing the keymap layer disposes that root and stops signal updates.

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: Solid keymap

Related pages#

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