Simon Klee
508bf3e788
The embedded terminal sent no bytes for F1 through F12 in any form that the key parser recognizes, with or without modifiers, so F-key bindings in programs such as htop and Midnight Commander did nothing. It also dropped keys that a host terminal sends in SS3 form (`ESC O A` and the other arrows, Home and End in application cursor mode, keypad Enter in application keypad mode), Kitty F13 to F25, and the keypad Begin key. `physicalKey` turns a key event into the W3C key code that Ghostty's encoder needs. #1423 made it skip parser codes that start with `[`, but codes that start with `O` still went to Ghostty as `OP` or `OA`, which it does not know, and the name table had no F-keys. It now treats `O` codes like `[` codes and maps `f1`-`f25` to `F1`-`F25`. The child gets the key encoded for its own modes: Up from `ESC O A` sends `ESC [ A`, or `ESC O A` to a child in application cursor mode, and Alt+F5 sends `ESC [ 15;3 ~`. The parser calls the keypad Begin key (`CSI E`, `SS3 E`, Kitty 57427) `clear`. It now maps to `NumpadBegin`, which Ghostty encodes as the same key: `CSI E`, `SS3 E` in application cursor mode, `CSI 1;5 E` with Ctrl, and `CSI 57427 u` to a Kitty child. Some keys still give no bytes because Ghostty has no encoding for them: the menu key (`CSI 29 ~`, Kitty 57363), F26 to F35, and F13 to F25 to a child that is not in Kitty mode. Kitty-only names such as the keypad navigation keys, the lock keys and the modifier keys are also still dropped; they will be filed separately. A sweep checks that every key name in the parser's table except `menu` encodes to bytes, and rows in the `preserves` table give the exact bytes for F-keys with Ctrl and Alt, SS3 keys, Kitty F13 and F25, and keypad Begin in default, application cursor, application keypad and Kitty modes. Reverting the `O` check, deleting the F-key line, moving either end of the F-key range, or deleting or renaming the Begin entry each makes at least one row fail. Fixes #1606
OpenTUI is a library to build terminal user interfaces.
- It is written in Zig.
- You write TypeScript directly or through React and Solid.
- You arrange boxes and text with flexbox.
- You add selects, inputs, and scroll boxes with keyboard and mouse controls.
- You can play sounds, show images, and render 3D graphics.
OpenCode uses OpenTUI in production for millions of users.
Website | Documentation | Packages
Packages
@opentui/core- Native terminal UI library with TypeScript bindings.@opentui/react- React renderer for building terminal user interfaces with OpenTUI Core.@opentui/solid- Solid renderer for building terminal user interfaces with OpenTUI Core.@opentui/keymap- Key binding and command routing library for terminal and browser applications.@opentui/qrcode- QR code encoder and renderable with React and Solid surfaces.@opentui/three- Three.js WebGPU renderer for OpenTUI.@opentui/ssh- SSH server integration for OpenTUI applications.
Private packages
@opentui/native- Private workspace with the Zig implementation, native tests, and benchmarks.@opentui/examples- Private workspace with example applications and a standalone examples executable.@opentui/web- Private workspace with the documentation website and the AI agent skill.
AI agent skill
Install the OpenTUI documentation as a skill for your AI coding assistant with npx skills:
npx skills add anomalyco/opentui --skill opentui
Add -g to install the skill globally.
Development
Development requires Bun 1.4.1 or later and Zig 0.16.0.
See AGENTS.md for engineering, tooling, and verification conventions.
bun install
Run package scripts from their package directory. Run bun run build from the repository root after you change
native code or cross-package build outputs. Ordinary TypeScript changes do not require a root build.
Run repository tests and static checks from the repository root:
bun run test
bun run fmt:check
bun run lint
To link the source packages into a Bun-managed project, install that project's dependencies, then run
./scripts/link-opentui-dev.sh /path/to/project from the repository root. Add --react or --solid when needed.
Contributing
OpenTUI is open for contributions.
License
OpenTUI is licensed under the MIT License.