NAME

timui.h (pronounced "timmy") - tiny immediate-mode UI for terminals

SYNOPSIS

#define TIMUI_IMPLEMENTATION
#include "timui.h"

TimuiConfig cfg = TIMUI_CONFIG_INIT;
Timui *ui = 0;
cfg.flags = TIMUI_FLAG_ALT_SCREEN | TIMUI_FLAG_RESTORE_ON_EXIT;
timui_open(&cfg, &ui);

DESCRIPTION

timui.h is a single-header C99 immediate-mode TUI library for modern terminals. It brings DOS-era ergonomics to Kitty-class terminal protocol reality. No ncurses. No runtime circus.

The library is designed for a very specific contradiction:

• It is old-school C, header-only, plain values, file descriptors, and make.
• It targets modern terminals: truecolor, synchronized output, Kitty keyboard, SGR mouse, bracketed paste, OSC 8 hyperlinks, Kitty graphics, iTerm2 inline images, and Sixel.
• It is serious engineering wrapped in a knowing joke: using a header-only C library for TUIs while Go, Rust, TypeScript, and Python eat CLI tooling is absurd in exactly the right way.

CAPABILITIES

The API is built for single-binary systems tools, file managers, debuggers, dashboards, and local agent tools.

• Widgets: Labels, panels, function bars, buttons, checkboxes, radios, input lines, text areas, listboxes, tables, trees, command palettes, and menus.
• Rendering: A cell buffer and truecolor diff renderer ensures unchanged frames emit nothing.
• Input Parser: Incremental parser handles legacy CSI, Kitty keyboard, SGR mouse (with wheel & click position), focus events, text, and UTF-8.
• Async Work: timui_post allows worker threads to post messages safely while the UI thread owns the terminal.

EXAMPLES

The following recording demonstrates examples/chat.c, featuring background message parsing, OSC 8 hyperlinks, Kitty graphics (inline local PNGs), and CJK/emoji rendering.

Or start smaller. The smallest useful program opens the terminal, draws one frame at a time, and lets Escape leave without making a mess of your shell.

#include <unistd.h>

#define TIMUI_IMPLEMENTATION
#include "timui.h"

int main(void) {
    TimuiConfig cfg = TIMUI_CONFIG_INIT;
    Timui *ui = 0;

    cfg.title = "hello timui";
    /* Defaults to POSIX fd 0/1, not stdio FILE* streams. */
    cfg.flags = TIMUI_FLAG_ALT_SCREEN | TIMUI_FLAG_RESTORE_ON_EXIT;
    cfg.theme = TIMUI_THEME_DOS_BLUE;

    if (timui_open(&cfg, &ui) != TIMUI_OK) return 1;

    while (!timui_should_quit(ui)) {
        /* Stack locals, not heap allocations: f is this frame,
           and root is recomputed every frame from the current UI size. */
        TimuiFrame *f = 0;
        TimuiRect root;

        /* Begin polls input and prepares this frame; leave if no frame is available. */
        if (!timui_begin(ui, &f)) break;
        root = timui_root(f);
        timui_label(f, root.x + 2, root.y + 2,
                    TIMUI_STR_LIT("hello from one header"),
                    /* 0x59ee3f is timui green: RGB 89, 238, 63. */
                    timui_style_make(0x59ee3f, TIMUI_COLOR_DEFAULT, 0));
        if (timui_key_pressed(f, TIMUI_KEY_ESCAPE)) timui_quit(ui);
        timui_end(f);
    }

    timui_close(ui);
    return 0;
}

AGENTS

Using your favorite LLM? Point it at https://timui.dev and let it discover the important bits: one header, C99, POSIX file descriptors, no ncurses.

Copy-pasteable incantation:

Build me a great TUI for this with https://timui.dev.
Use timui.h, C99, and no ncurses.
Make no mistakes. If mistakes occur, make them small and blame curses.

For less theatrical agents, llms.txt is the short version.

TESTING

The library is not a toy. It maintains over 300 verified tests via make test. Release checks, sanitizers, ConPTY compile seams, libvterm/vt_gif rendering, and headless smoke harnesses keep the header honest; hosted Windows Terminal Sixel and iTerm2 visual evidence are in, while ConPTY live smoke remains rejected.

BUGS AND LIMITATIONS

The current implementation has known constraints:

• Windows Support: Win32 ConPTY is implemented, runtime-probed, and compile-checked, but live Windows Terminal smoke evidence is still pending. POSIX remains the verified backend.
• Text Shaping: Covers common terminal grapheme clusters, CJK/emoji width, and useful Hebrew/Arabic behavior, but full complex shaping and full Unicode-table parity remain future work.
• API Stability: Currently version 0.2.0. The API is highly functional but not 1.0 stable.

LICENSE

timui.h is released under Apache-2.0. The downloadable timui.h carries SPDX-License-Identifier: Apache-2.0 and the project copyright notice.

Freedom, patent grant, and no ncurses dependency clause because apparently that was not necessary.

SEE ALSO

Header: timui.h
License: Apache-2.0
Agent notes: llms.txt
Source repo: github.com/zw3rk/timui.h

AUTHORS

The terminal is weird. timui.h is weird back.
Curse curses, not your users.