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"),
    ]
};

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
├── tests/
│   └── Hex1b.Tests/        # Unit tests
└── apphost.cs              # Aspire app host for running samples

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