TUI.zig

A modern, feature-rich Terminal User Interface library for Zig

Documentation | API Reference | Quick Start | Contributing

---

TUI.zig is a Modern and easy-to-use Terminal User Interface (TUI) library for the Zig programming language. It provides a rich set of features to create modern, responsive, and visually appealing terminal applications with minimal effort.

Note

This project is actively maintained and contributions are welcome. See our Contributing Guide for details.

---

Features (click to expand)

Feature	Description	Documentation
True Color (24-bit RGB)	Full spectrum color support for modern terminals.	https://muhammad-fiaz.github.io/tui.zig/guide/styling
256 Color Palette	Fallback color support for older terminals.	https://muhammad-fiaz.github.io/tui.zig/guide/styling
16 ANSI Colors	Universal compatibility with basic terminal colors.	https://muhammad-fiaz.github.io/tui.zig/guide/styling
Double Buffering	Flicker-free rendering by buffering entire screen.	https://muhammad-fiaz.github.io/tui.zig/api/renderer
Diff-Based Updates	Only redraw changed cells for optimal performance.	https://muhammad-fiaz.github.io/tui.zig/api/renderer
Unicode Support	Full grapheme cluster handling for international text.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets
Wide Character Support	CJK and emoji rendering with proper width calculation.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets
Keyboard Events	Full key detection with modifiers (Ctrl, Alt, Shift).	https://muhammad-fiaz.github.io/tui.zig/guide/events
Mouse Support	Click, drag, scroll, and hover event handling.	https://muhammad-fiaz.github.io/tui.zig/guide/events
Bracketed Paste	Safe paste mode to distinguish typed vs pasted input.	https://muhammad-fiaz.github.io/tui.zig/guide/events
Focus Events	Window focus detection for responsive applications.	https://muhammad-fiaz.github.io/tui.zig/guide/events
Raw Mode	Direct terminal control for real-time input.	https://muhammad-fiaz.github.io/tui.zig/api/terminal
Text Widget	Styled text with alignment and wrapping.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#text
Button Widget	Clickable buttons with hover states and callbacks.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#button
Input Field	Single-line text input with cursor navigation.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#input-field
Text Area	Multi-line text editing with scrolling.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#text-area
Checkbox	Toggle checkboxes with state management.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#checkbox
Radio Button	Single selection groups for mutually exclusive options.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#radio-button
Progress Bar	Visual progress indicators with customizable styles.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#progress-bar
Spinner	Animated loading indicators with multiple presets.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#spinner
List View	Scrollable item lists with selection support.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#list-view
Table	Data tables with columns, rows, and sorting.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#table
Tabs	Tabbed navigation for organizing content.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#tabs
Modal	Dialog overlays for focused interactions.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#modal
Scroll View	Scrollable containers for overflow content.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#scroll-view
Split View	Resizable panes for multi-panel layouts.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#split-view
Badge	Status indicators with variants and sizes.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#badge
Card	Container widgets with titles and content.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#card
Tooltip	Contextual information on hover.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#tooltip
Accordion	Collapsible content sections.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#accordion
Breadcrumb	Navigation path indicators.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#breadcrumb
Sidebar	Navigation sidebars with items.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#sidebar
Status Bar	Application status displays.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#status-bar
Toast	Notification messages with auto-dismiss.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#toast
Skeleton	Loading placeholders with animations.	https://muhammad-fiaz.github.io/tui.zig/guide/widgets#skeleton
Rich Text Styling	Bold, italic, underline, strikethrough formatting.	https://muhammad-fiaz.github.io/tui.zig/guide/styling
Built-in Themes	Default, Dark, Light, Nord, Dracula, Gruvbox themes.	https://muhammad-fiaz.github.io/tui.zig/guide/styling#themes
Custom Themes	Create your own color schemes with theme builder.	https://muhammad-fiaz.github.io/tui.zig/guide/styling#custom-themes
Border Styles	Single, double, rounded, thick, ASCII border styles.	https://muhammad-fiaz.github.io/tui.zig/guide/styling#borders
Flex Layout	Flexible row/column layouts with constraints.	https://muhammad-fiaz.github.io/tui.zig/guide/layout
Box Model	Padding, margin, and border support.	https://muhammad-fiaz.github.io/tui.zig/guide/layout#box-model
Constraints	Min/max sizing for responsive layouts.	https://muhammad-fiaz.github.io/tui.zig/guide/layout#constraints
Alignment	Start, center, end, stretch alignment options.	https://muhammad-fiaz.github.io/tui.zig/guide/layout#alignment
Easing Functions	Linear, ease-in, ease-out, bounce, elastic curves.	https://muhammad-fiaz.github.io/tui.zig/guide/animation
Tween Animations	Smooth value interpolation for transitions.	https://muhammad-fiaz.github.io/tui.zig/guide/animation#tween
Timer System	Scheduled callbacks for timed operations.	https://muhammad-fiaz.github.io/tui.zig/guide/animation#timers
FPS Counter	Performance monitoring for optimization.	https://muhammad-fiaz.github.io/tui.zig/api/renderer#fps

---

Prerequisites and Supported Platforms (click to expand)

Prerequisites

Before using TUI.zig, ensure you have the following:

Requirement	Version	Notes
Zig	0.16.0+	Download from ziglang.org
Operating System	Windows 10+, Linux, macOS	Cross-platform terminal support

---

Supported Platforms

TUI.zig is validated on these architectures:

Platform	x86_64 (64-bit)	aarch64 (ARM64)	x86 (32-bit)
Linux	Yes	Yes	Yes
Windows	Yes	Yes	Yes
macOS	Yes	Yes (Apple Silicon)	No

Cross-Compilation

Zig makes cross-compilation easy. Build for any target from any host:

# Build for Linux ARM64 from Windows
zig build -Dtarget=aarch64-linux

# Build for Windows from Linux  
zig build -Dtarget=x86_64-windows

# Build for macOS Apple Silicon from Linux
zig build -Dtarget=aarch64-macos

# Build for 32-bit Windows
zig build -Dtarget=x86-windows

---

Quick Start

Installation

Stable Release (Recommended)

zig fetch --save "https://github.com/muhammad-fiaz/tui.zig/archive/refs/tags/0.0.2.tar.gz"

Development (Latest)

Install the latest development version from the main branch:

zig fetch --save git+https://github.com/muhammad-fiaz/tui.zig.git

Then add to your build.zig:

const tui_dep = b.dependency("tui", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("tui", tui_dep.module("tui"));

Hello World

const std = @import("std");
const tui = @import("tui");

pub fn main() !void {
    // Create application
    var app = try tui.App.init(.{});
    defer app.deinit();

    // Create a simple widget
    var hello = HelloWidget{};
    try app.setRoot(&hello);

    // Run the event loop
    try app.run();
}

const HelloWidget = struct {
    pub fn render(self: *HelloWidget, ctx: *tui.RenderContext) void {
        _ = self;
        var screen = ctx.getSubScreen();

        // Center the message
        const msg = "Hello, TUI.zig!";
        const x = (screen.width -| 18) / 2;
        const y = screen.height / 2;

        screen.setStyle(tui.Style.default
            .setFg(tui.Color.rgb(100, 200, 255))
            .bold());
        screen.moveCursor(x, y);
        screen.putString(msg);
    }

    pub fn handleEvent(self: *HelloWidget, event: tui.Event) tui.EventResult {
        _ = self;
        if (event == .key) {
            if (event.key.modifiers.ctrl and event.key.key == .char) {
                if (event.key.key.char == 'c') {
                    return .quit;
                }
            }
        }
        return .ignored;
    }
};

Interactive Counter

const std = @import("std");
const tui = @import("tui");

const Counter = struct {
    count: i32 = 0,

    pub fn render(self: *Counter, ctx: *tui.RenderContext) void {
        var screen = ctx.getSubScreen();
        screen.clear();

        // Display count
        var buf: [32]u8 = undefined;
        const text = std.fmt.bufPrint(&buf, "Count: {d}", .{self.count}) catch "?";

        screen.setStyle(tui.Style.default.setFg(tui.Color.cyan).bold());
        screen.moveCursor(2, 2);
        screen.putString(text);

        // Instructions
        screen.setStyle(tui.Style.default.dim());
        screen.moveCursor(2, 4);
        screen.putString("Up/Down to change, Ctrl+C to quit");
    }
    pub fn handleEvent(self: *Counter, event: tui.Event) tui.EventResult {
        switch (event) {
            .key => |k| switch (k.key) {
                .up => { self.count += 1; return .needs_redraw; },
                .down => { self.count -= 1; return .needs_redraw; },
                else => {},
            },
            else => {},
        }
        return .ignored;
    }
};

pub fn main() !void {
    var app = try tui.App.init(.{});
    defer app.deinit();

    var counter = Counter{};
    try app.setRoot(&counter);
    try app.run();
}

---

Testing

# Run all tests
zig build test

# Run with verbose output
zig build test -- --verbose

---

Documentation

Full documentation is available at muhammad-fiaz.github.io/tui.zig

• Getting Started - Installation and first app
• Widgets - Built-in widget reference
• Styling - Colors, themes, and styling
• Layout - Layout system guide
• Events - Event handling
• API Reference - Complete API docs

---

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

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

---

Support

If you find TUI.zig useful, consider:

• Starring the repository
• Reporting bugs or suggesting features
• Improving documentation
• Sponsoring development

---

Made with care by Muhammad Fiaz