Repository navigation
📦 Published to pub.dev: dart_tui 3.0.0
This major release makes raw mode behave like Bubble Tea on macOS and Linux, decodes input one Unicode scalar at a time, validates timers and forms in every build mode, and removes two leftover APIs. It also fixes the hang that kept every program reading default stdin alive after it quit (#15). The full macOS validation is in docs/quality/2026-10-17-macos-3.0.0-validation.md.
Breaking changes
View.setContentremoved. Assign the field instead:view.content = 'Hello';.Form.fieldIndexForTestremoved. Test observable state instead, such asform.valuesorform.view().content.- Ctrl+C, Ctrl+Z and other control keys are key messages on macOS and Linux. Raw mode now also clears ISIG, IEXTEN and IXON. Ctrl+C no longer raises SIGINT, so
Programno longer turns it intoInterruptMsgand quits for you. Ctrl+Z no longer stops the process, which used to leave the terminal broken. Handle the keys inupdate.kill -INTstill deliversInterruptMsg. Ctrl+, Ctrl+S, Ctrl+Q, Ctrl+V and Ctrl+Y also arrive as keys.if (msg is KeyMsg) { switch (msg.key) { case 'ctrl+c': return (this, () => quit()); case 'ctrl+z': return (this, suspend); // optional job control } }
- One key event per Unicode scalar. Adjacent printable bytes are no longer merged into one
KeyPressMsg. An unbracketed paste ofhellois five events. A grapheme cluster such as 👨👩👧 or e + U+0301 arrives as several events. Malformed UTF-8 producesunknownkeys instead of stalling input. Appendmsg.keyEvent.textfor each event, and handlePasteMsgfor pasted text. - Timer helpers validate durations when called.
everythrowsArgumentErrorfor a zero or negative interval.tickandtickWithIdthrow for a negative delay. Before,every(Duration.zero, ...)failed later with a division by zero. - Forms validate their input at construction in every build mode.
FormthrowsArgumentErrorfor no groups, an empty group, or duplicate field keys across groups.Field.selectOfandField.multiSelectOfthrow when given both or neither ofoptions/optionsFor. Multi-select fields throw on duplicate option values. Before, only debug asserts checked some of these. - Default stdin belongs to the main isolate. A
ProgramwithoutwithInputmust run in the main isolate; elsewhererun()throwsStateError. Readers in several isolates used to race for input and could close stdin for the whole process.await Isolate.run(() => Program(options: [withInput(null)]).run(model));
- SIGTERM quits gracefully. It enqueues
QuitMsg, so the terminal is restored andrun()returns. AwithFilterthat vetoesQuitMsgalso vetoes SIGTERM. Before, the process died with the terminal left in the alternate screen. metais no longer a dependency. If you importedpackage:metathrough dart_tui, add it to your ownpubspec.yaml.
Behavior changes
- Programs exit when
run()returns. A helper isolate reads default stdin, so stdin no longer keeps the process alive after the last program. Sequential programs (prompts, gum helpers) still share input, stdin stays open afterwards, andwithInput(stdin)uses the same shared reader. - Commands end with the program. Timers that a command starts (
tick,every,Future.delayed, ...) are cancelled when the program ends. execProcessowns the terminal input. While an inherited child runs, no program reads stdin. A child started right after startup no longer receives the terminal's replies to the startup queries; the exec waits up to 500 ms for them, once.sequenceno longer blocks input. Its commands still run in order, but other messages are processed while a step is pending. A sequence stops after a step throws or returnsQuitMsg/InterruptMsg.- Text widgets accept bracketed paste. Focused
TextInputModel,TextAreaModelandpromptInputinsertPasteMsgcontent with control characters removed. AFormroutes the paste to the active field. ForwardPasteMsgto your widgets as well asKeyMsg. - Multi-select and dynamic selects keep selections by value. Values that disappear from
optionsForare dropped, and reordered options keep the selection. An untouchedoptionsForselect submits its first option, like a static select, instead ofnull. - Form focus skips hidden fields, hidden groups and notes, including at the start of the form, and hidden groups never receive input.
- More keys are named. ESC + key arrives as
alt+<key>(alt+a,alt+enter,ctrl+alt+a) instead ofunknown. NUL isctrl+space; 0x1C–0x1F arectrl+\,ctrl+],ctrl+^andctrl+_; SS3 arrows areup/down/left/right; SGR wheel-left/right decode aswheelLeft/wheelRight. - The final frame is rendered on quit, and leaving the alternate screen no longer prints a blank line.
- Mouse wheel events scroll
ListModel,TableModelandTreeModel. ListModelfilter mode: Up/Down and Ctrl+P/Ctrl+N move through the matches while typing, so gumfilter()returns the highlighted match.FilePickerModelshows load errors (error) instead of an empty list, ignores keys while a directory loads, clampscursor,scrollOffsetandheight, and addscopyWith(clearSelected: true).
Fixes
- Inline (non-alt-screen) programs leave the shell prompt directly below the view on exit. Before, it landed on the last changed row, inside the view.
- Typing a combining mark or a multi-scalar emoji no longer crashes
TextInputModelor misplaces text inTextAreaModel. - Backspace in list filters and
promptInputdeletes a whole grapheme, andpromptInputaccepts Space. - List mouse clicks select the right item when only some items have descriptions; navigation is safe with an empty list or no filter matches.
Field.input(placeholder:)renders;optionsForselects show their options before the first edit.- Table headers align with their rows, and the selected tree branch keeps its highlight.
- Canvas layers with equal z-index keep their paint order.
- Input stream errors quit cleanly and restore the terminal, and a throttled frame is never written after the terminal is released or the program is killed.
- Timer errors show the rejected duration.
- Fixed several examples:
shopping_list,showcase,http,package_manager,cursor_model,gmail,canvas,isbn_form,list_mutationandfile_picker.
Performance
TextInputModelre-segments only the end of the value when text is appended: 25,000 single-character inserts take 0.95 s, down from 1.7 s in 2.1.0.
Tooling and docs
- A new
sdk-floorCI job runs analysis and tests on Dart 3.5.4, and the dev dependency ranges now resolve there. - PTY smoke tests require each example to exit on its own after quit, and cover paste and Space.
tool/compile_examples.shreports failed compiles.- Re-recorded all 60 VHS example GIFs.
Known limitations
- Inline (non-alt-screen) rendering still starts at row 1 and can overwrite earlier shell output (#18).
- On Windows, the first input meant for an
execProcesschild can reach the program instead.