ArthurSonzogni/FTXUI

Documentation · Report a Bug · Examples . Request Feature · Send a Pull Request
Doc: English | Français | Español | 繁體中文 | 简体中文 | 日本語 |

Functional Terminal (X) User interface

A simple cross-platform C++ library for terminal based user interfaces!

• Functional style. Inspired by 1 and React
• Simple and elegant syntax (in my opinion)
• Keyboard & mouse navigation.
• Support for UTF8 and fullwidth chars (→ 测试)
• Support for animations. Demo 1, Demo 2
• Support for drawing. Demo
• No dependencies.
• C++20 Module support
• Cross platform: Linux/MacOS (main target), WebAssembly, Windows (Thanks to contributors!).
• Learn by examples, and tutorials
• Multiple packages:
  • CMake FetchContent (preferred)
  • Bazel
  • vcpkg
  • Conan Debian package
  • Ubuntu package
  • Arch Linux
  • OpenSUSE
  • XMake repository package
  • Nix
  • Amalgamated (single-header/source) (from 7.0.0)
  • conda-forge
• Good practices: documentation, tests, fuzzers, performance tests, automated CI, automated packaging, etc...

• Starter CMake
• Starter Bazel
• Documentation
• Examples (WebAssembly)
• Build using CMake
• Build using Bazel
• Build using Meson

#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;
}

FTXUI is organized into three modules:

1. screen: Low-level rendering (colors, pixels, terminal)
2. dom: Layout and composition (hierarchical elements)
3. component: User interaction (widgets, events, main loop)

For most users, including everything at once is the simplest way to start:

• Header: #include <ftxui/ftxui.hpp>
• CMake target: ftxui::ftxui
• Bazel target: @ftxui//:ftxui

This module defines a hierarchical set of Element. An Element manages layout and can be responsive to the terminal dimensions.

They are declared in <ftxui/dom/elements.hpp>

Element document = vbox({
    text("top"),
    separator(),
    text("bottom"),
}) | border;

Element paragraph(string text);
Element paragraphAlignLeft(string text);
Element paragraphAlignRight(string text);
Element paragraphAlignCenter(string text);
Element paragraphAlignJustify(string text);

ftxui/component produces dynamic UI, reactive to the user's input. It defines a set of ftxui::Component. A component reacts to Events (keyboard, mouse, resize, ...) and Renders as an Element (see previous section).

Prebuilt components are declared in <ftxui/component/component.hpp>

• Want to share a useful Component for FTXUI? Feel free to add yours here
• ftxui-grid-container
• ftxui-ip-input
• ftxui-image-view: For Image Display.
• ftxui-image-view-async: Fork of the original, without image reloads and conversions on every frame redraw.
• ftxui-navigation-tree
• MarkdownFTXUI: Markdown Editor/Viewer for the terminal.

Feel free to add your projects here:

• json-tui
• git-tui
• rgb-tui
• chrome-log-beautifier

• 2048-cpp
• BestEdrOfTheMarket
• Captain's log
• Caravan
• CryptoCalculator
• FTB - tertminal file browser
• FTowerX
• Fallout terminal hacking
• Lazylist
• Memory game
• nfolens
• Path Finder
• Pigeon ROS TUI
• SHOOT!
• StartUp
• Step-Writer
• TUISIC
• Terminal Animation
• TimeAccumulator
• UDP chat
• VerifySN (Fast Hash Tool)
• XJ music
• beagle-config
• cachyos-cli-installer
• eCAL monitor
• ftxuiFileReader
• ftxui_CPUMeter
• hastur
• i3-termdialogs
• inLimbo
• keywords (Play web version ❤️)
• ltuiny
• openJuice
• ostree-tui
• OvenbirdBT
• pciex
• resource-monitor
• rw-tui
• simpPRU
• sweeper (Play web version ❤️)
• tabdeeli
• terminal-rain
• tic-tac-toe
• tiles
• todoman
• turing_cmd
• typing-speed-test
• vantage
• x86-64 CPU Architecture Simulation
• C++ Process Manager
• Baobab TUI Remake
• Youtube Music Client
• TUI_DB
• Tpedia - Terminal Wikipedia

Several games using the FTXUI have been made during the Game Jam:

• TermBreaker [Play web version]
• Minesweeper Marathon [Play web version]
• Grand Rounds
• LightsRound
• DanteO
• Sumo
• Drag Me aROUND
• DisarmSelfDestruct
• TheWorld
• smoothlife
• Consu

It is highly recommended to use CMake FetchContent to depend on FTXUI so you may specify which commit you would like to depend on.

include(FetchContent)
FetchContent_Declare(ftxui
  GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
  GIT_TAG v7.0.3
)
FetchContent_MakeAvailable(ftxui)

target_link_libraries(your_target PRIVATE
    # Use the umbrella target (recommended)
    ftxui::ftxui

    # Or chose a submodule
    # ftxui::component
    # ftxui::dom
    # ftxui::screen
)

MODULE.bazel

bazel_dep(
    name = "ftxui",
    version = "7.0.3",
)

BUILD.bazel

cc_binary(
    name = "your_target",
    srcs = ["your_source.cc"],
    deps = [
        # Choose submodules
        "@ftxui//:component",
        "@ftxui//:dom",
        "@ftxui//:screen",
        
        # Or use the single ftxui target (includes all modules)
        # "@ftxui//:ftxui",
    ],
)

FTXUI can also be built using Meson. See doc/installation_meson.md for detailed instructions.

meson setup builddir
ninja -C builddir

To use FTXUI as a subproject in your Meson project, create a subprojects/ftxui.wrap file or use it as a dependency:

ftxui_dep = dependency('ftxui-component')

If you don't, FTXUI may be used from the following packages:

• CMake FetchContent (preferred),
• Bazel,
• vcpkg,
• Conan
• Debian package,
• Ubuntu package,
• Arch Linux,
• OpenSUSE,
• Nix,

If you choose to build and link FTXUI yourself, ftxui-component must be first in the linking order relative to the other FTXUI libraries, i.e.

g++ . . . -lftxui-component -lftxui-dom -lftxui-screen . . .

To build FTXUI with modules, check documentation