Getting Started

Table of Contents

• The Three Modules
• Installation and Dependency
• Your First Static UI (DOM)
• Adding Interactivity (Component)
• Next Steps

FTXUI is a functional, C++ library for terminal-based user interfaces. It is organized into three main modules, each building upon the previous one.

The Three Modules

1. Screen: The lowest level. It handles the terminal's state, colors, and raw character grid.
2. DOM: The layout engine. It provides a set of Elements that can be composed to create complex, responsive layouts.
3. Component: The interactive layer. It handles user input (keyboard, mouse) and manages the application's main loop.

Installation and Dependency

To set up FTXUI in your project, follow the installation guide.

The most recommended way for CMake users is to use FetchContent. Add this to your CMakeLists.txt:

include(FetchContent)
FetchContent_Declare(ftxui
  GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
  GIT_TAG main # or a specific version like v6.1.9
)
FetchContent_MakeAvailable(ftxui)
 
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE ftxui::ftxui)

Your First Static UI (DOM)

The DOM module allows you to describe your UI declaratively. Compositing elements is as simple as nesting function calls or using the pipe operator for decorators.

Save this as main.cpp:

#include <ftxui/dom/elements.hpp>
#include <ftxui/screen/screen.hpp>
 
int main() {
  using namespace ftxui;
 
  // Define the document structure
  Element document = vbox({
    text("FTXUI Getting Started") | bold | center,
    separator(),
    hbox({
      text("Left Panel") | border,
      vbox({
        text("Main Content Area") | flex,
        separator(),
        text("Footer Information") | dim,
      }) | border | flex,
    }) | flex,
  });
 
  // Create the screen and render
  auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
  Render(screen, document);
  screen.Print();
 
  return 0;
}

Adding Interactivity (Component)

To handle user input and create a dynamic application, use the Component module and the App class. Components manage their own state and can be composed using containers.

#include <ftxui/component/component.hpp>
#include <ftxui/component/app.hpp>
#include <ftxui/dom/elements.hpp>
 
int main() {
  using namespace ftxui;
 
  std::vector<std::string> entries = {
      "Entry 1",
      "Entry 2",
      "Entry 3",
  };
  int selected = 0;
 
  // Create a menu component
  auto menu = Menu(&entries, &selected);
 
  // You can decorate components using the pipe operator.
  auto component = menu | border;
 
  // Start the main loop
  auto app = App::TerminalOutput();
  app.Loop(component);
 
  return 0;
}

Next Steps

• Browse the Examples to see what's possible.
• Check out the Starter Template for a pre-configured project structure.

Previous	Next
Introduction	Modules