Getting Started

Hex1b is a .NET library for building terminal user interfaces (TUI). If you are familiiar with the way that React is used in the browser to construct a virtual DOM which is then synchronized with the real browser DOM then this should feel familiar.

Prerequisites

• .NET 10 or later
• A terminal that supports ANSI escape sequences (most modern terminals do)

Create a New Console Application

First, create a new console application:

dotnet new console -n MyTodoApp && cd MyTodoApp

Install Hex1b

Add the Hex1b package to your project:

dotnet add package Hex1b --version {{version}}

Step 1: Hello World

Let's start with a simple "Hello World" example. Replace the contents of Program.cs:

csharp

dotnet run

Press Ctrl+C to exit.

The fluent API uses the ctx (context) parameter to create widgets. In this case, ctx.Text() creates a text widget.

Step 2: Adding State and Interactivity

Now let's add a button and some state to track clicks:

csharp

dotnet run

Key concepts:

• State: We created a CounterState class to hold mutable data
• Border: The ctx.Border() creates a widget with a border and optional title
• Collection expressions: [...] syntax creates an array of child widgets
• Button: The ctx.Button() creates an interactive button; use .OnClick() for the click handler

Step 3: Building a Todo List

Let's build a simple todo list that displays items and lets you toggle them:

csharp

dotnet run

New concepts:

• VStack: ctx.VStack() arranges children vertically
• List widget: ctx.List() creates a scrollable, selectable list; use .OnItemActivated() for activation events
• Fill: .Fill() makes a widget expand to fill available space
• InfoBar: ctx.InfoBar() displays help text pinned to the bottom of the screen
• Navigation: Use arrow keys to navigate, Space or Enter to toggle items

Step 4: Adding New Items

Let's add the ability to create new todo items with a text input:

csharp

dotnet run

New concepts:

• HStack: ctx.HStack() arranges children horizontally
• TextBox: ctx.TextBox() creates an editable text input; use .OnTextChanged() to handle changes
• Separator: new SeparatorWidget() creates a horizontal line divider
• Focus: Use Tab to move focus between interactive widgets

Step 5: Complete Todo Application

Let's add a few more features to complete our todo app:

csharp

dotnet run

Final features:

• Remaining count: Shows how many items are not yet complete
• Selection tracking: .OnSelectionChanged() tracks which list item is selected
• Delete functionality: Removes the selected item
• Multiple event handlers: Chain .OnSelectionChanged() and .OnItemActivated() for different behaviors

What You've Learned

Through this tutorial, you've learned:

✅ How to create a console application and install Hex1b
✅ The fluent API using context (ctx) to build widgets
✅ State management with simple classes
✅ Layout with Border, VStack, and HStack
✅ Interactive widgets: Button, TextBox, List
✅ Event handling for user input
✅ Collection expressions for composing UIs

Next Steps

• Widgets & Nodes - Understand the core architecture
• Layout System - Master the constraint-based layout
• Input Handling - Learn about keyboard shortcuts and focus
• Theming - Customize the appearance of your app