termbox2

termbox2 is a terminal I/O library for creating TUIs. It is a slim alternative to the ubiquitous ncurses library. Unlike ncurses, it has a tighter API, and comes with built-in support for popular terminals if a terminfo db is not present on the system.

Compared to the original termbox, it retains a simple API and no dependencies beyond libc, and adds stricter error checking, more efficient escape sequence parsing, opt-in support for 32-bit color, extended grapheme clusters, code gen for built-in escape sequences, a test suite, and more.

termbox2 is organized as a single file header library, though it is possible to compile it as a stand-alone shared or static library.

keyboard demo

Synopsis

#define TB_IMPL
#include "termbox2.h"

int main(int argc, char **argv) {
    struct tb_event ev;
    int y = 0;

    tb_init();

    tb_printf(0, y++, TB_GREEN, 0, "hello from termbox");
    tb_printf(0, y++, 0, 0, "width=%d height=%d", tb_width(), tb_height());
    tb_printf(0, y++, 0, 0, "press any key...");
    tb_present();

    tb_poll_event(&ev);

    y++;
    tb_printf(0, y++, 0, 0, "event type=%d key=%d ch=%c", ev.type, ev.key, ev.ch);
    tb_printf(0, y++, 0, 0, "press any key to quit...");
    tb_present();

    tb_poll_event(&ev);
    tb_shutdown();

    return 0;
}

API

The basic API is pretty self-explanatory. Consult the header file itself for the complete API and documentation.

int tb_init();
int tb_shutdown();

int tb_width();
int tb_height();

int tb_clear();
int tb_present();

int tb_set_cursor(int cx, int cy);
int tb_hide_cursor();

int tb_set_cell(int x, int y, uint32_t ch, uintattr_t fg, uintattr_t bg);

int tb_peek_event(struct tb_event *event, int timeout_ms);
int tb_poll_event(struct tb_event *event);

int tb_print(int x, int y, uintattr_t fg, uintattr_t bg, const char *str);
int tb_printf(int x, int y, uintattr_t fg, uintattr_t bg, const char *fmt, ...);

How to use termbox2

As mentioned above, there are two options:

Copy (or git submodule) termbox2.h into your C project. As normal, include the header file wherever you want to use tb_* functions, but also be sure to #define TB_IMPL in exactly one of your source files. (This is a common pattern for single file header libraries.) Ensure that feature test macros _DEFAULT_SOURCE and _XOPEN_SOURCE are defined (either by defining them via compiler flags or including termbox2.h first[^1]).
Build termbox2 as a library (either make libtermbox2.so or make libtermbox2.a) and link as normal. Make sure the compile-time options remain the same for libtermbox2 and your application. (Alternatively, build with make lib and use termbox2.h.lib instead of termbox2.h. This will guarantee that the same TB_LIB_OPTS-gated compile-time options are used in the library and the header file.)

Language bindings

Basic FFI or ABI-compatible examples in the languages below are in the demo/ directory. (Feel free to submit PRs for other languages.)

Other wrapper libraries:

Using termbox2 with other libraries

termbox2 does not contain TUI elements/widgets like input fields, checkboxes, scoll bars, etc. These are too complex and opinionated and better off handled by a separate library. Here are some widget examples built on top of termbox2:

readline - if all you need is a text input
termbox-widgets

termbox2 also does not contain a layout engine for the same reason. However, there is at least one layout engine with termbox2 support: Clay.

Examples

mle - flexible terminal-based text editor
newsraft - feed reader for terminal
ictree - like tree but interactive
lavat - lava lamp for the terminal
termbox-tetris - Tetris clone
dvd-screensaver - a terminal screensaver
matrix-tui - Matrix client
Vgmi - Gemini client
poe - .po file editor
xtxf - 2D matrix screensaver
chatty - chat application
ly - TUI display manager for Linux and BSD
kew - terminal music player

[^1]: See https://github.com/termbox/termbox2/pull/75#issuecomment-2252242269

Termbox2

Install / Use

README