https://github.com/termbox/termbox2

terminal I/O library
https://github.com/termbox/termbox2

curses ncurses termcap terminal terminfo tui

Last synced: 5 months ago
JSON representation

terminal I/O library

Host: GitHub
URL: https://github.com/termbox/termbox2
Owner: termbox
License: mit
Created: 2021-09-07T01:42:56.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2026-01-02T03:38:16.000Z (5 months ago)
Last Synced: 2026-01-07T20:35:37.018Z (5 months ago)
Topics: curses, ncurses, termcap, terminal, terminfo, tui
Language: C
Homepage:
Size: 223 KB
Stars: 621
Watchers: 15
Forks: 52
Open Issues: 12
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-c - termbox2 - terminal I/O library for creating TUIs. [MIT](https://spdx.org/licenses/MIT.html) (Utilities / YAML)
awesome-c - termbox2 - terminal I/O library for creating TUIs. [MIT](https://spdx.org/licenses/MIT.html) (Utilities / YAML)
awesome-tuis - termbox2

README

          # termbox2

termbox2 is a terminal I/O library for creating TUIs. It is a slim alternative

to the ubiquitous [ncurses](https://invisible-island.net/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](https://github.com/termbox/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](demo/keyboard.gif)

### Synopsis

```c

#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.

```c

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:

1. 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]).

2. 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.)

* [D](demo/example.d)

* [Go](demo/example.go)

* [Nim](demo/example.nim)

* [PHP](demo/example.php)

* [Python](demo/example.py)

* [Ruby](demo/example.rb)

* [Rust](demo/example.rs)

* [Zig](demo/example.zig)

Other wrapper libraries:

* [cl-termbox2 (Common Lisp)](https://github.com/garlic0x1/cl-termbox2)

* [termbox.cr (Crystal)](https://github.com/thmisch/termbox.cr)

* [termbox2.cr (Crystal)](https://github.com/homonoidian/termbox2.cr)

* [Termbox.pm (Perl)](https://github.com/sanko/Termbox.pm)

* [termbox2-hs (Haskell)](https://github.com/gatlin/termbox2-hs)

* [termbox2-zig (Zig)](https://sr.ht/~kolunmi/termbox2-zig)

* [termbox2-node (JavaScript)](https://github.com/RauliL/termbox2-node)

* [letloop's termbox2 (Chez Scheme)](https://github.com/letloop/letloop/)

* [odin-termbox2 (Odin)](https://github.com/sudokit/odin-termbox2)

### 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](demo/readline.c) - if all you need is a text input

* [termbox-widgets](https://github.com/git-bruh/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](https://github.com/nicbarker/clay).

### Examples

* [mle](https://github.com/adsr/mle) - flexible terminal-based text editor

* [newsraft](https://codeberg.org/newsraft/newsraft) - feed reader for terminal

* [ictree](https://github.com/NikitaIvanovV/ictree) - like tree but interactive

* [lavat](https://github.com/AngelJumbo/lavat) - lava lamp for the terminal

* [termbox-tetris](https://github.com/zacharygraber/termbox-tetris) - Tetris clone

* [dvd-screensaver](https://github.com/yamin-shihab/dvd-screensaver) - a terminal screensaver

* [matrix-tui](https://github.com/git-bruh/matrix-tui) - Matrix client

* [Vgmi](https://github.com/RealMelkor/Vgmi) - Gemini client

* [poe](https://sr.ht/~strahinja/poe/) - `.po` file editor

* [xtxf](https://github.com/charlesrocket/xtxf) - 2D matrix screensaver

* [chatty](https://git.spacehb.net/chatty) - chat application

* [ly](https://codeberg.org/fairyglade/ly) - TUI display manager for Linux and BSD

* [kew](https://codeberg.org/ravachol/kew) - terminal music player

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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/termbox/termbox2

Awesome Lists containing this project

README