OpenTUI
Notes from building terminal interfaces with OpenTUI. What the renderer gives you, what it leaves to you, and where it has to be patched.
OpenTUI renders a component tree into a
terminal. @opentui/core holds the layout and paint engine, and framework
renderers sit on top of it, @opentui/react among them. Writing against it is
React work with the browser's guarantees removed. There is no CSS, no
subpixels, no accessibility tree, one font metric, and a canvas that is a grid
of cells the user can resize mid-frame.
Each note here is written from code that ran, and says where the approach stops working.
How this is organised
Patches. What breaks, the workaround, and the condition under which the workaround can be deleted.
Features. Behaviour worth building once, such as input, focus, layout and rendering, with what each one assumes about the terminal.
Components. Reusable pieces, each with the composition and keyboard model it assumes.
A note belongs here when the answer took hours to find rather than minutes. Where OpenTUI's own documentation already says it plainly, these notes link to it instead of repeating it.
Everything in this category
patches/
- Clipping box bordersOpenTUI's native box draw ignored the scissor stack, so a bordered box painted its border over everything around its scroll container. Fixed upstream in 0.6.0; kept for the detour it describes.
- Making drag-selection opt-inOpenTUI's text renderables are selectable by default, so a click-to-navigate UI starts a drag-selection instead. Flipping the default without disabling selection.
- Terminal-relative dimensionsGiving a negative width or height the meaning "terminal size minus that many cells", re-resolved on every resize, since OpenTUI percentages resolve against the parent.
features/
- Reading the host terminal's coloursSubscribing to the terminal's own palette from React, including the DEC mode OpenTUI never enables and the cache the poll fallback has to clear.
- A theme that follows the terminalSemantic colour roles over a static catalogue and the live terminal palette, with light and dark read from the terminal background rather than declared.