Hex1b

Hex1b is a .NET library for building rich, interactive terminal user interfaces (TUI) with a React-inspired declarative API. Create beautiful console applications with widgets, layouts, theming, and more.

• Declarative UI - Build UIs using a widget tree pattern inspired by React and Flutter
• Widget Library - TextBlock, TextBox, Button, List, VStack, HStack, Splitter, and more
• Layout System - Flexible constraint-based layout with size hints (Fill, Content, Fixed)
• Theming - Built-in themes with customizable colors and styles
• Input Handling - Keyboard navigation, focus management, and shortcut bindings
• Reconciliation - Efficient diff-based updates to minimize terminal redraws

dotnet add package Hex1b

Here's a simple "Hello World" application:

using Hex1b;
using Hex1b.Widgets;

using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };

using var app = new Hex1bApp(
    ctx => Task.FromResult<Hex1bWidget>(
        new VStackWidget([
            new TextBlockWidget("Hello, Terminal!"),
            new ButtonWidget("Exit", () => cts.Cancel())
        ])
    )
);

await app.RunAsync(cts.Token);

Hex1b provides a variety of built-in widgets:

Hex1b uses a constraint-based layout system with size hints:

// Children with size hints: first fills available space, second sizes to content
new VStackWidget(
    [contentWidget, statusBarWidget],
    [SizeHint.Fill, SizeHint.Content]
);

Size Hints:

• SizeHint.Fill - Expand to fill available space
• SizeHint.Content - Size to fit content
• SizeHint.Fixed(n) - Fixed size of n units

Define keyboard bindings at any level of your widget tree:

var widget = new SplitterWidget(left, right, 25) with
{
    InputBindings = [
        InputBinding.Ctrl(Hex1bKey.S, Save, "Save"),
        InputBinding.Ctrl(Hex1bKey.Q, Quit, "Quit"),
    ]
};

Picking portable bindings. Different terminals intercept different combos before they reach Hex1b (e.g. Windows Terminal eats Ctrl+Shift+↑/↓ for scroll, GNOME Terminal eats Ctrl+Shift+T/N/W for tab/window management). See Keybinding Portability on hex1b.dev for the per-terminal interception matrix and recommendations, and use the KeyBindingTester sample to confirm what actually fires on your target terminals.

Apply built-in themes or create your own:

using var app = new Hex1bApp(builder, new Hex1bAppOptions { Theme = Hex1bThemes.Sunset });

Hex1b follows a widget/node separation pattern:

1. Widgets - Immutable configuration objects describing what to render
2. Nodes - Mutable render objects that manage state and layout
3. Reconciliation - Efficient diffing to update nodes when widgets change

┌─────────────────────────────────────────────────────────────┐
│                      Hex1bApp.RunAsync()                    │
├─────────────────────────────────────────────────────────────┤
│  1. Build widget tree (your code)                           │
│  2. Reconcile → Update node tree                            │
│  3. Layout → Measure and arrange nodes                      │
│  4. Render → Draw to terminal                               │
│  5. Wait for input → Dispatch to focused node               │
│  6. Repeat from step 1                                      │
└─────────────────────────────────────────────────────────────┘

The samples/ directory contains example applications demonstrating various features:

• Cancellation - Master-detail contact editor with save/cancel functionality

This repository is set up with Aspire to make it easy to run and test sample applications:

dotnet run --project apphost.cs

Note: Aspire doesn't natively support interactive terminal applications, but this project explores techniques to make TUI app development and testing in Aspire possible.

• .NET 10.0 SDK (preview)
• A terminal emulator with good ANSI support

dotnet build

dotnet test

hex1b/
├── src/
│   └── Hex1b/              # Main library
│       ├── Layout/         # Constraint-based layout system
│       ├── Nodes/          # Render nodes (mutable, stateful)
│       ├── Widgets/        # Widget definitions (immutable config)
│       ├── Theming/        # Theme system and built-in themes
│       └── Input/          # Keyboard input and bindings
├── samples/                # Example applications
├── docs/                   # Architecture & reference documentation
├── tests/
│   └── Hex1b.Tests/        # Unit tests
└── apphost.cs              # Aspire app host for running samples

Full documentation lives at hex1b.dev. Highlights:

• Input Handling — focus, routing, declarative bindings, and Vim/Emacs-style remap walkthrough.
• Keybinding Portability — per-terminal interception matrix (Windows Terminal, ConPTY, macOS Terminal.app, iTerm2, Ghostty, kitty, GNOME Terminal, Ptyxis, xterm, tmux, ssh) plus cross-cutting ANSI protocol limits.
• Terminal Emulator — using the embedded terminal widget.
• API Reference — generated namespace docs.

In-repo design / architecture notes (not on the website):

• docs/terminal.md — Presentation/workload adapter architecture.
• docs/child-process-arch.md — Child process / PTY architecture.
• docs/muxer-protocol.md — Muxer wire protocol.

For the manual portability harness used to generate the per-terminal data, see samples/KeyBindingTester.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

For AI coding agents, see AGENTS.md for context and conventions.

This project is licensed under the MIT License - see the LICENSE file for details.

• Spectre.Console - Beautiful console output
• Terminal.Gui - Cross-platform terminal UI toolkit
• Aspire - Cloud-ready stack for .NET