dart_tui

Elm-style terminal UI framework for Dart, inspired by Bubble Tea.

Build rich, interactive CLI applications with a clean Model–Update–View architecture, a full component library, and Lipgloss-quality styling — all in pure Dart.

📖 Documentation & component gallery — browse every component, block and guide with live previews.

---

Features

• Model–Update–View — same architecture as Elm and Bubble Tea; pure, testable state
• Async commands (Cmd) for timers, HTTP, subprocesses, and any async work
• 17 ready-made components — spinners, progress bars, text inputs, tables, trees, multi-select, list with fuzzy filter, tabbed views, in-line cursor, and more — plus huh-style forms
• One-shot helpers — promptSelect / promptConfirm / promptInput, plus gum-style filter, spin, and pager
• Spring animation — harmonica-style damped-spring easing for smooth progress, scroll, and cursor motion
• Readline editing keys — emacs bindings in text input & area (ctrl+a/e/b/f/w, alt-word motion, ctrl+w)
• File logging — FileLog writes diagnostics to a file without corrupting the rendered UI
• Lipgloss-inspired styling — true-color RGB, borders with titles, padding, word-wrap, gradients, SGR attributes
• Style utilities — getWidth(), getHeight(), truncate(), truncateLeft(), per-side border flags, tabWidth, marginBackground
• Style inheritance — Style.inherit(parent) fills unset fields; CompleteColor for per-profile color downgrade
• Canvas compositing — paint styled blocks at arbitrary (x, y) positions with z-index layering
• Diffing renderers — line-level diff by default; opt-in cell-level diff (withCellRenderer()) writes only changed cells
• Synchronized updates (CSI ?2026) for terminals that support them
• Auto background detection — OSC 11 query fires at startup; your model receives BackgroundColorMsg
• Fluent ProgramOption functions — withAltScreen(), withHideCursor(), withTickInterval(), withMouseCellMotion(), withMouseAllMotion(), withReportFocus(), withWindowSize(), withLogFile()
• Fast startup — kernel snapshots cut first-frame time from ~550 ms (JIT) to ~160 ms; AOT compiles to native

---

Installation

# pubspec.yaml
dependencies:
  dart_tui: ^3.0.0

dart pub get

Migrating from 2.x? Version 3.0 delivers Ctrl+C and Ctrl+Z to update as keys instead of quitting or suspending for you, sends one key event per Unicode scalar, validates timers and forms at construction, and removes View.setContent (assign view.content). See the 3.0.0 changelog for the complete migration notes.

Migrating from 1.x? Version 2.0 removes the TeaModel, LegacyKeyMsg, TuiStyle, and ProgramOptions compatibility APIs. Use Model, KeyPressMsg/KeyMsg, immutable Style, and a single Program(options: <ProgramOption>[...]) configuration path. See the 2.0.0 changelog for the complete migration notes.

---

Quick start

import 'package:dart_tui/dart_tui.dart';

void main() async {
  await Program(
    options: [withAltScreen()],
  ).run(CounterModel());
}

final class CounterModel extends Model {
  CounterModel({this.count = 0});
  final int count;

  @override
  Cmd? init() => tick(const Duration(seconds: 1), (_) => _TickMsg());

  @override
  (Model, Cmd?) update(Msg msg) {
    if (msg is _TickMsg) {
      if (count >= 5) return (this, () => quit());
      return (CounterModel(count: count + 1),
          tick(const Duration(seconds: 1), (_) => _TickMsg()));
    }
    if (msg is KeyMsg && (msg.key == 'q' || msg.key == 'ctrl+c')) {
      return (this, () => quit());
    }
    return (this, null);
  }

  @override
  View view() => newView('Count: $count\n\nPress q to quit.');
}

final class _TickMsg extends Msg {}

---

Core concepts

Model–Update–View

┌──────────────┐   Msg    ┌──────────────┐
│    Model     │ ──────▶  │    update    │
│  (your state)│          │  (pure fn)   │
└──────────────┘          └──────┬───────┘
        ▲                        │ (Model, Cmd?)
        │                        ▼
        │                 ┌──────────────┐
        └──── render ───  │     view     │
                          │  (pure fn)   │
                          └──────────────┘

Concept	Description
Model	Immutable state. Implement init(), update(Msg), view().
Msg	Tagged event: key press, window resize, tick, custom data.
Cmd	FutureOr<Msg?> Function() — async side-effect that delivers one message back.
View	Declared output string plus optional cursor position, mouse mode, window title.
Program	Owns the event loop, terminal raw mode, renderer, and signal handling.

Returning a value (prompt-style)

abstract class OutcomeModel<T> implements Model {
  T? get outcome; // non-null → program exits and returns this value
}

final String? result = await Program().runForResult<String>(MyPromptModel());

This is the beginning of the README. Read the rest at the original. Read the full README ↗