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: TUI.zig is under active development. so expect frequent updates and improvements.

✨ Features

TUI.zig provides a comprehensive Terminal User Interface library with cross-platform support:

🎨 Rendering & Display

• True Color (24-bit RGB) - Full spectrum color support
• 256 Color Palette - Fallback for older terminals
• 16 ANSI Colors - Universal compatibility
• Double Buffering - Flicker-free rendering
• Diff-Based Updates - Only redraw changed cells
• Unicode Support - Full grapheme cluster handling
• Wide Character Support - CJK and emoji rendering

🖱️ Input Handling

• Keyboard Events - Full key detection with modifiers
• Mouse Support - Click, drag, scroll, and hover
• Bracketed Paste - Safe paste mode
• Focus Events - Window focus detection
• Raw Mode - Direct terminal control

🧩 Widget System

• Text - Styled text with alignment and wrapping
• Button - Clickable buttons with hover states
• Input Field - Single-line text input with cursor
• Text Area - Multi-line text editing
• Checkbox - Toggle checkboxes
• Radio Button - Single selection groups
• Progress Bar - Visual progress indicators
• Spinner - Animated loading indicators
• List View - Scrollable item lists
• Table - Data tables with columns
• Tabs - Tabbed navigation
• Modal - Dialog overlays
• Scroll View - Scrollable containers
• Split View - Resizable panes
• more...

🎭 Styling & Themes

• Rich Text Styling - Bold, italic, underline, strikethrough
• Built-in Themes - Default, Dark, Light, Nord, Dracula, Gruvbox
• Custom Themes - Create your own color schemes
• Border Styles - Single, double, rounded, thick, ASCII

📐 Layout System

• Flex Layout - Flexible row/column layouts
• Box Model - Padding, margin, borders
• Constraints - Min/max sizing
• Alignment - Start, center, end, stretch

🎬 Animation

• Easing Functions - Linear, ease-in, ease-out, bounce, elastic
• Tween Animations - Smooth value interpolation
• Timer System - Scheduled callbacks
• FPS Counter - Performance monitoring

🌍 Cross-Platform

• Linux - Full terminal support
• macOS - Native terminal integration
• Windows - Console API support
• BSD/Unix - POSIX compatibility

---

🚀 Quick Start

Installation

Add TUI.zig to your project using Zig's package manager:

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("↑/↓ 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 ❤️ by Muhammad Fiaz