These docs describe the main branch, including unreleased changes. Read the 0.8.0 docs.

OpenTUI 0.8.0

2026-10-29npm GitHub release

Most of 0.8.0 makes each frame cheaper. In 0.7.0, every frame cleared and repainted the whole screen and compared every row with the terminal, even when only a spinner had moved. Now an unchanged frame paints nothing, and a frame with a small change repaints only the rows around it. In OpenCode, a frame with a spinner or a streamed line does about a twentieth of the cell operations it did.

ScrollBox now scrolls and follows new content in native code. Animations share one clock: before, an app with several animations could draw twice as many frames as the animations needed.

The native input parser is still opt-in. It now keeps a mouse wheel report that a slow link splits, which the default parser can type into the focused input as text. To try it, set OTUI_NATIVE_INPUT_PARSER=1, or pass experimental_nativeInput: true to the renderer.

Wide emoji sequences, such as a family emoji in tmux, draw at their full width, and long wrapped or highlighted lines draw their last rows as fast as their first.

In 0.7.0, a ScrollBox was twelve scene nodes. It kept its scroll position in four copies, followed its sticky edge through a six-flag state machine, and learned its range from two separate resize hooks. Because the viewport size and the content size came from different hooks, a frame in which the box and its content grew together reset the position to 0. Vertical viewport padding left the last rows out of reach, and the scrollbar thumb was half a cell until the first terminal resize. In 0.8.0, a ScrollBox is one box with a native scroll control. After each layout solve, native code computes the range, follows the sticky edge, clamps the offset, and shows or hides the bars, all from one layout. Following new content no longer needs a round trip to JavaScript.

That change has a cost for code that reached into the parts. wrapper, viewport, content, and the two scrollbars are now views of the native state, not renderables. They still have geometry, colors, padding, and their events, but they have no children of their own. Children of a ScrollBox report the ScrollBox as their parent, and a press on a scrollbar targets the ScrollBox. Code that compared a node with the content part now compares it with the ScrollBox itself:

// 0.7.0
if (node === scroll.content) return
// 0.8.0
if (node === scroll) return

With the scroll state in native code, a scroll can also wait for layout. Before, an app that loaded older messages above the reader and then corrected the position had to wait two animation frames, and the reader saw one frame at the old position. Now scrollTo and scrollBy apply again after the next frame’s layout, and anchor holds a row in place while the content above it changes. Release the anchor in afterLayout, so that the frame that lays out the new rows still holds the place:

const release = scrollbox.anchor(firstVisibleRow)
await loadOlderMessages()
scrollbox.afterLayout(release)

In an OpenCode transcript, this took the shifted frames during a backfill from 1 to 0, and the in-between frames over 6 message jumps from 6 to 0.

An animation slower than the renderer, such as a spinner, used to have two options. It could set live: true, which runs the loop at targetFps and keeps renderer.idle() from resolving. Or it could run its own timer that calls requestRender(). With timers, every component gets its own frames, so three components at 20, 12.5, and 10 fps drew 40 frames per second. renderer.onAnimationTick puts every subscriber on one clock. Due times are multiples of 1000 / fps, so equal rates tick together. Each frame, whatever its cause, also runs every tick that is due within its tolerance. The same three components now draw 20 frames per second, and OpenCode during an agent turn draws 26 instead of 52 to 55:

const frames = ["⠋", "⠙", "⠹", "⠸"]
let i = 0
const stop = renderer.onAnimationTick(12.5, () => {
  spinner.content = frames[i++ % frames.length]
})

A renderable can set animationFps instead. React components use useAnimationTick, and Solid components use onAnimationTick.

Before 0.8.0, OpenTUI wrapped every frame in synchronized output (CSI ? 2026 h … CSI ? 2026 l), even when the terminal never reported mode 2026. Over a slow link, those wrappers cost bytes on every frame. A tmux between the app and the link redraws each line that an update touched when the update ends, so a streaming scene sent 64 KB/s instead of 41 KB/s. On a 48 KB/s SSH link, that is a lag of 2.0 s instead of 75 ms. The new default, synchronizedOutput: "auto", removes the wrapper in a remote session once the startup replies arrive, but only when the terminal did not report mode 2026, or when the app writes to process.stdout inside tmux, screen, or Zellij on its own host. In the multiplexer case, OpenTUI gives up whole frames to save bytes, so tmux can show partial frames. If you want whole frames on a slow link, set synchronizedOutput: "always".

Breaking changes

core: The wrapper, viewport, content, verticalScrollBar, and horizontalScrollBar of a ScrollBox are facade objects (ScrollBoxWrapper, ScrollBoxViewport, ScrollBoxContent, ScrollBoxBar), not renderables. Children report the ScrollBox as their parent, so compare a node with the ScrollBox, not with scroll.content. See ScrollBox. (#1805)
core: ScrollBox scrollbars have no slider, startArrow, or endArrow, overflow is always "hidden", getChildrenCount() counts the rows, and primaryAxis follows the content direction. ScrollBox ignores renderable options on its parts outside each part’s supported color, layout, padding, bar, and callback fields, and viewport padding that is not whole cells throws. See ScrollBox. (#1805)
core: RenderContext requires the clock and onAnimationTick fields, so a custom RenderContext must implement them. The renderer and the scrollback snapshot context supply both. See Custom renderables. (#1814, #1803)
core: The protected Renderable._hasFocusedDescendant field is removed, so a subclass that reads it gets undefined. Read hasFocusedDescendant instead, and use FFIRenderLib.contextDrawSceneBody() instead of contextDrawSceneText(). See Custom renderables. (#1778)
native: OT_SCENE_RECORD_SCENE_TEXT is now OT_SCENE_RECORD_SCENE_BODY, and ot_buffer_draw_scene_text is now ot_buffer_draw_scene_body, with the same value and layout. The reserved field of ot_scene_stats is now damage_rows. See C. (#1778, #1783)
native: In the Zig module, a CliRenderer exists only as the renderer of a Session, and Context.drawSceneText and drawSceneTextOn are now drawSceneBody and drawSceneBodyOn. BufferedOutput and the standalone create, render, and setup calls are removed, so render through a Session. See Zig. (#1806, #1778)

Added

Changed

Fixed

Security

solid: @opentui/solid uses babel-preset-solid 1.9.16. Solid releases before 1.9.16 depend on Seroval versions with a critical advisory (GHSA-p6vx-979v-rg4c), so install solid-js 1.9.16 or later. See Solid bindings. (#1786)

API changes#

`@opentui/core`#

Added

Changed

Removed

method FFIRenderLib.contextDrawSceneText({ context, target, frame }: NativeDrawingTarget, node: SceneNodeHandle, x: number, y: number): void
method ScrollBoxRenderable.add(obj: Renderable | VNode<any, any[]>, index?: number): number
method ScrollBoxRenderable.getChildren(): Renderable[]
method ScrollBoxRenderable.getRenderable(id: string): Renderable | undefined
method ScrollBoxRenderable.insertBefore(obj: Renderable | VNode<any, any[]> | unknown, anchor?: Renderable | unknown): number
method ScrollBoxRenderable.remove(child: BaseRenderable): void
protected property Renderable._hasFocusedDescendant: boolean
static property ScrollBoxRenderable.idCounter: number
property ScrollBoxRenderable.padding: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingBottom: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingLeft: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingRight: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingTop: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingX: number | `${number}%` | null | undefined
property ScrollBoxRenderable.paddingY: number | `${number}%` | null | undefined

`@opentui/core/testing`#

Added

property TestRendererOptions.nativeSceneVerify?: boolean

`@opentui/react`#

Added

const useAnimationTick: (fps: number | undefined, callback: AnimationTickCallback, options?: AnimationTickOptions) => void

`@opentui/solid`#

Added

const onAnimationTick: (fps: number | Accessor<number | undefined>, callback: AnimationTickCallback, options?: AnimationTickOptions) => void

`opentui.h`#

Added

Removed

const OT_SCENE_RECORD_SCENE_TEXT = 10
field ot_scene_stats.reserved: uint32_t, offset 220
function ot_buffer_draw_scene_text(ot_context *, const ot_handle *target, const ot_scene_frame_request *, const ot_handle *node, int32_t x, int32_t y): ot_status

OpenTUI 0.8.0

Breaking changes

Added

Changed

Fixed

Security

API changes#

@opentui/core#

@opentui/core/testing#

@opentui/react#

@opentui/solid#

opentui.h#

`@opentui/core`#

`@opentui/core/testing`#

`@opentui/react`#

`@opentui/solid`#

`opentui.h`#