Skip to content
Ratatui

Component Template

Features

  • Uses tokio for async events
    • Start and stop key events to shell out to another TUI like vim
    • Supports suspend signal hooks
  • Logs using tracing
  • better-panic
  • color-eyre
  • human-panic
  • Clap for command line argument parsing
  • Component trait with Home and Fps components as examples

Usage

You can start by using cargo-generate:

Terminal window
cargo install cargo-generate
cargo generate --git https://github.com/ratatui-org/templates component --name ratatui-hello-world
cd ratatui-hello-world

You can also use a template.toml file to skip the prompts:

Terminal window
$ cargo generate --git https://github.com/ratatui-org/templates component --template-values-file ./path/to/template.toml --name ratatui-hello-world
# OR generate from local clone
$ git clone https://github.com/ratatui-org/templates
$ cd templates
$ cargo generate --path ./component --template-values-file ./.github/workflows/template.toml --name ratatui-hello-world

Run

Terminal window
cargo run # Press `q` to exit

Show help

Terminal window
$ cargo run -- --help
Hello World project using ratatui-template


Usage: ratatui-hello-world [OPTIONS]


Options:
  -t, --tick-rate <FLOAT>   Tick rate, i.e. number of ticks per second [default: 1]
  -f, --frame-rate <FLOAT>  Frame rate, i.e. number of frames per second [default: 60]
  -h, --help                Print help
  -V, --version             Print version

Show version

Without direnv variables:

Terminal window
$ cargo run -- --version
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/ratatui-hello-world --version`
ratatui-hello-world v0.1.0-47-eb0a31a


Authors: Dheepak Krishnamurthy


Config directory: /Users/kd/Library/Application Support/com.kdheepak.ratatui-hello-world
Data directory: /Users/kd/Library/Application Support/com.kdheepak.ratatui-hello-world

With direnv variables:

Terminal window
$ direnv allow
direnv: loading ~/gitrepos/component-template/ratatui-hello-world/.envrc
direnv: export +RATATUI_HELLO_WORLD_CONFIG +RATATUI_HELLO_WORLD_DATA +RATATUI_HELLO_WORLD_LOG_LEVEL


$ # OR


$ export RATATUI_HELLO_WORLD_CONFIG=`pwd`/.config
$ export RATATUI_HELLO_WORLD_DATA=`pwd`/.data
$ export RATATUI_HELLO_WORLD_LOG_LEVEL=debug


$ cargo run -- --version
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/ratatui-hello-world --version`
ratatui-hello-world v0.1.0-47-eb0a31a


Authors: Dheepak Krishnamurthy


Config directory: /Users/kd/gitrepos/component-template/ratatui-hello-world/.config
Data directory: /Users/kd/gitrepos/component-template/ratatui-hello-world/.data

Documentation

Read documentation on design decisions in the template here: https://ratatui.rs/templates/component/

Background

ratatui is a Rust library to build rich terminal user interfaces (TUIs) and dashboards. It is a community fork of the original tui-rs created to maintain and improve the project.

The source code of this project is an opinionated template for getting up and running with ratatui. You can pick and choose the pieces of this template to suit your needs and sensibilities. This rest of this documentation is a walk-through of why the code is structured the way it is, so that you are aided in modifying it as you require.

ratatui is based on the principle of immediate rendering with intermediate buffers. This means that at each new frame you have to build all widgets that are supposed to be part of the UI. In short, the ratatui library is largely handles just drawing to the terminal.

Additionally, the library does not provide any input handling nor any event system. The responsibility of getting keyboard input events, modifying the state of your application based on those events and figuring out which widgets best reflect the view of the state of your application is on you.

The ratatui-org project has added a template that covers the basics, and you find that here: https://github.com/ratatui-org/templates/tree/main/simple.

I wanted to take another stab at a template, one that uses tokio and organizes the code a little differently. This is an opinionated view on how to organize a ratatui project.

This project also adds commonly used dependencies like logging, command line arguments, configuration options, etc.

As part of this documentation, we’ll walk through some of the different ways you may choose to organize your code and project in order to build a functioning terminal user interface. You can pick and choose the parts you like.

You may also want to check out the following links (roughly in order of increasing complexity):