Guide · Open source
How to use FTXUI: build terminal UIs in C++
Updated · written with AI from the project's own documentation and checked against our catalogue data
FTXUI is an open-source C++ library for drawing interactive user interfaces inside a terminal window, with layouts, colors, borders, buttons, and mouse or keyboard input. This guide is for C++ developers who want to build console tools and need to know how to get the library, describe a layout, and render it. By the end you will understand the three modules, the basic element tree, and where to find the build and example files.
FTXUIArthurSonzogni/FTXUI · ★ 10.9k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone on the FTXUI repository. You need a C++ compiler and CMake, Bazel, or Meson installed.
- 2Pick a build system. Choose CMake, Bazel, or Meson and follow the matching build guide from the documentation links.
- 3Include the header. Add #include <ftxui/ftxui.hpp> and use the ftxui namespace, or include only the modules you need.
- 4Describe the layout. Build an element tree with vbox, hbox, text, and decorators such as border and flex.
- 5Create a screen and render. Call Screen::Create(Dimension::Full()), then Render(screen, document), then screen.Print().
- 6Explore the examples. Open the examples page to see gridbox, flexbox, colors, and animation demos.
What FTXUI is and when to use it
FTXUI stands for Functional Terminal (X) User interface. It is a simple cross-platform C++ library for terminal based user interfaces. The interface is described in a functional style as a tree of elements, which is then drawn to the terminal.
It is meant for text-based tools that run in a console. It does not open a graphical desktop window, and the README describes only a C++ library, so it is not a fit for people who are not writing C++.
- Good fit: interactive command-line tools written in C++ that need boxes, grids, gauges, and keyboard or mouse input.
- Good fit: projects that want no external dependencies, since the README lists none.
- Poor fit: graphical desktop applications, because FTXUI renders to the terminal.
- Poor fit: teams that need Windows as a primary target, since the README lists Linux and macOS as the main targets and Windows support as coming from contributors.
Get the source and choose a build system
The README's install method is to clone the repository and build it. Its listed prerequisites are a C++ compiler and one of CMake, Bazel, or Meson. Clone the project with the command below.
The README lists several ways to consume the library: CMake FetchContent (listed as preferred), Bazel, vcpkg, Conan, and a number of Linux distribution packages. Starter projects for CMake and Bazel are linked from the documentation section, and build guides exist for CMake, Bazel, and Meson.
- Build using CMake, Bazel, or Meson (installation_meson.md is linked in the README).
- Starter CMake project: ftxui-starter. Starter Bazel project: ftxui-bazel.
git clone https://github.com/ArthurSonzogni/FTXUIKnow the three modules
FTXUI is organized into three modules. For most users, including everything at once is the simplest way to start. The header is ftxui/ftxui.hpp, the CMake target is ftxui::ftxui, and the Bazel target is @ftxui//:ftxui.
- screen: low-level rendering (colors, pixels, terminal).
- dom: layout and composition, using hierarchical elements.
- component: user interaction, including widgets, events, and the main loop.
Build a layout with elements
An Element manages layout and can respond to the terminal dimensions. You combine elements horizontally with hbox, vertically with vbox, in a grid with gridbox, or wrapped along one direction with flexbox. The flex decorator makes an element flexible.
Decorators can be applied with a pipe operator, so element | border | flex is equivalent to flex(border(element)). The README also supports the nested form decorator1(decorator2(element)).
- Style decorators include bold, italic, dim, inverted, underlined, underlinedDouble, blink, strikethrough, color, bgcolor, and hyperlink.
- Separators are created with separator() and boxes with the border decorator.
- Colors: the README says FTXUI supports every color palette and links a color gallery.
Element document = vbox({
text("top"),
separator(),
text("bottom"),
}) | border;Render a complete example
The README's first example builds a vertical box that holds a horizontal box of three bordered text elements and three gauges. It then creates a screen sized to the full terminal, renders the document into it, and prints the screen.
Copy the example below into a C++ file, include it with your build system, and run it. The code is taken from the README.
- Screen::Create(Dimension::Full()) creates a screen that fills the terminal.
- Render(screen, document) draws the element tree into the screen.
- screen.Print() writes the result to the terminal.
#include <ftxui/ftxui.hpp>
using namespace ftxui;
int main() {
auto document =
vbox({
hbox({
text("one") | border,
text("two") | border | flex,
text("three") | border | flex,
}),
gauge(0.25) | color(Color::Red),
gauge(0.50) | color(Color::White),
gauge(0.75) | color(Color::Blue),
});
auto screen = Screen::Create(Dimension::Full());
Render(screen, document);
screen.Print();
return 0;
}Add keyboard and mouse input
The README says FTXUI supports keyboard and mouse navigation and describes the component module as the place for widgets, events, and the main loop. The README does not show an interactive example in the portion provided, so check the linked documentation and examples for the exact component API.
- Browse the examples: https://arthursonzogni.github.io/FTXUI/examples/
- Read the documentation: https://arthursonzogni.github.io/FTXUI/
What people use it for
- Build a terminal dashboard that shows gauges and bordered panels, as in the README example.
- Create a text-based configuration tool with keyboard navigation.
- Draw grid or flexible layouts inside a console window.
- Add colored status text and separators to command-line utilities.
Frequently asked questions
Is FTXUI free to use?
FTXUI is released under the MIT licence, as shown in the README. The repository states this licence on its page, so check the LICENSE file in the repository for the full terms.
What do I need to install FTXUI?
The README lists a C++ compiler and one of CMake, Bazel, or Meson as prerequisites. The install method shown is cloning the repository and building it.
Does FTXUI have dependencies?
The README lists No dependencies as a feature. It is a C++ library used from your own code.
Does FTXUI work on Windows?
The README lists Linux and macOS as the main targets and says Windows is supported thanks to contributors. If Windows is your primary target, check the project's current status before committing.
How does FTXUI compare to ncurses?
Comparable projects named in the source are ncurses, Notcurses, and Textual. The README does not compare them directly, so review each project's documentation to decide which fits your needs.
Can I use FTXUI from Python or for a GUI app?
The README describes only a C++ library, and it renders to the terminal rather than a graphical window. For desktop windows or non-C++ code, the source does not suggest FTXUI is the right choice.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
FTXUI suits C++ developers who want interactive text-based tools with flexible layouts and no external dependencies. If you need a graphical window, are not writing C++, or require Windows as a first-class target, look at other options such as the comparable projects named in the source.
Install options & downloads