mirror of
https://github.com/ratatui-org/ratatui
synced 2024-11-29 08:00:38 +00:00
259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# Ratatui
|
|
|
|
<img align="left" src="https://avatars.githubusercontent.com/u/125200832?s=128&v=4">
|
|
|
|
`ratatui` is a [Rust](https://www.rust-lang.org) library that is all about cooking up terminal user interfaces.
|
|
It is a community fork of the original [tui-rs](https://github.com/fdehau/tui-rs)
|
|
project.
|
|
|
|
[](https://crates.io/crates/ratatui)
|
|
[](./LICENSE) [](https://github.com/ratatui-org/ratatui/actions?query=workflow%3ACI+)
|
|
[](https://docs.rs/crate/ratatui/)
|
|
[](https://deps.rs/repo/github/ratatui-org/ratatui)
|
|
[](https://app.codecov.io/gh/ratatui-org/ratatui)
|
|
[](https://discord.gg/pMCEU9hNEj)
|
|
[](https://matrix.to/#/#ratatui:matrix.org)
|
|
|
|
<!-- See RELEASE.md for instructions on creating the demo gif --->
|
|
|
|
|
|
<details>
|
|
<summary>Table of Contents</summary>
|
|
|
|
* [Ratatui](#ratatui)
|
|
* [Installation](#installation)
|
|
* [Introduction](#introduction)
|
|
* [Quickstart](#quickstart)
|
|
* [Status of this fork](#status-of-this-fork)
|
|
* [Rust version requirements](#rust-version-requirements)
|
|
* [Documentation](#documentation)
|
|
* [Examples](#examples)
|
|
* [Widgets](#widgets)
|
|
* [Built in](#built-in)
|
|
* [Third\-party libraries, bootstrapping templates and
|
|
widgets](#third-party-libraries-bootstrapping-templates-and-widgets)
|
|
* [Apps](#apps)
|
|
* [Alternatives](#alternatives)
|
|
* [Contributors](#contributors)
|
|
* [Acknowledgments](#acknowledgments)
|
|
* [License](#license)
|
|
|
|
</details>
|
|
|
|
## Installation
|
|
|
|
```shell
|
|
cargo add ratatui --features all-widgets
|
|
```
|
|
|
|
Or modify your `Cargo.toml`
|
|
|
|
```toml
|
|
[dependencies]
|
|
ratatui = { version = "0.23.0", features = ["all-widgets"]}
|
|
```
|
|
|
|
## Introduction
|
|
|
|
`ratatui` is a terminal UI library that supports multiple backends:
|
|
|
|
* [crossterm](https://github.com/crossterm-rs/crossterm) [default]
|
|
* [termion](https://github.com/ticki/termion)
|
|
* [termwiz](https://github.com/wez/wezterm/tree/master/termwiz)
|
|
|
|
The library is based on the principle of immediate rendering with intermediate buffers. This means
|
|
that at each new frame you should build all widgets that are supposed to be part of the UI. While
|
|
providing a great flexibility for rich and interactive UI, this may introduce overhead for highly
|
|
dynamic content. So, the implementation try to minimize the number of ansi escapes sequences
|
|
generated to draw the updated UI. In practice, given the speed of `Rust` the overhead rather comes
|
|
from the terminal emulator than the library itself.
|
|
|
|
Moreover, the library does not provide any input handling nor any event system and you may rely on
|
|
the previously cited libraries to achieve such features.
|
|
|
|
We keep a [CHANGELOG](./CHANGELOG.md) generated by [git-cliff](https://github.com/orhun/git-cliff)
|
|
utilizing [Conventional Commits](https://www.conventionalcommits.org/).
|
|
|
|
## Quickstart
|
|
|
|
The following example demonstrates the minimal amount of code necessary to setup a terminal and
|
|
render "Hello World!". The full code for this example which contains a little more detail is in
|
|
[hello_world.rs](./examples/hello_world.rs). For more guidance on how to create Ratatui apps, see
|
|
the [Docs](https://docs.rs/ratatui) and [Examples](#examples). There is also a starter template
|
|
available at [rust-tui-template](https://github.com/ratatui-org/rust-tui-template).
|
|
|
|
```rust
|
|
fn main() -> Result<(), Box<dyn Error>> {
|
|
let mut terminal = setup_terminal()?;
|
|
run(&mut terminal)?;
|
|
restore_terminal(&mut terminal)?;
|
|
Ok(())
|
|
}
|
|
|
|
fn setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>, Box<dyn Error>> {
|
|
let mut stdout = io::stdout();
|
|
enable_raw_mode()?;
|
|
execute!(stdout, EnterAlternateScreen)?;
|
|
Ok(Terminal::new(CrosstermBackend::new(stdout))?)
|
|
}
|
|
|
|
fn restore_terminal(
|
|
terminal: &mut Terminal<CrosstermBackend<Stdout>>,
|
|
) -> Result<(), Box<dyn Error>> {
|
|
disable_raw_mode()?;
|
|
execute!(terminal.backend_mut(), LeaveAlternateScreen,)?;
|
|
Ok(terminal.show_cursor()?)
|
|
}
|
|
|
|
fn run(terminal: &mut Terminal<CrosstermBackend<Stdout>>) -> Result<(), Box<dyn Error>> {
|
|
Ok(loop {
|
|
terminal.draw(|frame| {
|
|
let greeting = Paragraph::new("Hello World!");
|
|
frame.render_widget(greeting, frame.size());
|
|
})?;
|
|
if event::poll(Duration::from_millis(250))? {
|
|
if let Event::Key(key) = event::read()? {
|
|
if KeyCode::Char('q') == key.code {
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
})
|
|
}
|
|
```
|
|
|
|
## Status of this fork
|
|
|
|
In response to the original maintainer [**Florian Dehau**](https://github.com/fdehau)'s issue
|
|
regarding the [future of `tui-rs`](https://github.com/fdehau/tui-rs/issues/654), several members of
|
|
the community forked the project and created this crate. We look forward to continuing the work
|
|
started by Florian 🚀
|
|
|
|
In order to organize ourselves, we currently use a [Discord server](https://discord.gg/pMCEU9hNEj),
|
|
feel free to join and come chat! There is also a [Matrix](https://matrix.org/) bridge available at
|
|
[#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org).
|
|
|
|
While we do utilize Discord for coordinating, it's not essential for contributing.
|
|
Our primary open-source workflow is centered around GitHub.
|
|
For significant discussions, we rely on GitHub — please open an issue, a discussion or a PR.
|
|
|
|
Please make sure you read the updated [contributing](./CONTRIBUTING.md) guidelines, especially if
|
|
you are interested in working on a PR or issue opened in the previous repository.
|
|
|
|
## Rust version requirements
|
|
|
|
Since version 0.23.0, The Minimum Supported Rust Version (MSRV) of `ratatui` is 1.67.0.
|
|
|
|
## Documentation
|
|
|
|
The documentation can be found on [docs.rs.](https://docs.rs/ratatui)
|
|
|
|
## Examples
|
|
|
|
The demo shown in the gif above is available on all available backends.
|
|
|
|
```shell
|
|
# crossterm
|
|
cargo run --example demo
|
|
# termion
|
|
cargo run --example demo --no-default-features --features=termion
|
|
# termwiz
|
|
cargo run --example demo --no-default-features --features=termwiz
|
|
```
|
|
|
|
The UI code for this is in [examples/demo/ui.rs](./examples/demo/ui.rs) while the application state
|
|
is in [examples/demo/app.rs](./examples/demo/app.rs).
|
|
|
|
If the user interface contains glyphs that are not displayed correctly by your terminal, you may
|
|
want to run the demo without those symbols:
|
|
|
|
```shell
|
|
cargo run --example demo --release -- --tick-rate 200 --enhanced-graphics false
|
|
```
|
|
|
|
More examples are available in the [examples](./examples/) folder.
|
|
|
|
## Widgets
|
|
|
|
### Built in
|
|
|
|
The library comes with the following
|
|
[widgets](https://docs.rs/ratatui/latest/ratatui/widgets/index.html):
|
|
|
|
* [BarChart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
|
|
* [Block](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
|
|
* [Calendar](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
|
|
* [Canvas](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/struct.Canvas.html) which allows
|
|
rendering [points, lines, shapes and a world
|
|
map](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html)
|
|
* [Chart](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html)
|
|
* [Clear](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html)
|
|
* [Gauge](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html)
|
|
* [List](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html)
|
|
* [Paragraph](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
|
|
* [Scrollbar](https://docs.rs/ratatui/latest/ratatui/widgets/scrollbar/struct.Scrollbar.html)
|
|
* [Sparkline](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
|
|
* [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
|
|
* [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
|
|
|
|
Each widget has an associated example which can be found in the [examples](./examples/) folder. Run
|
|
each examples with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by
|
|
pressing `q`.
|
|
|
|
You can also run all examples by running `cargo make run-examples` (requires `cargo-make` that can
|
|
be installed with `cargo install cargo-make`).
|
|
|
|
### Third-party libraries, bootstrapping templates and widgets
|
|
|
|
* [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — Convert ansi colored text to
|
|
`ratatui::text::Text`
|
|
* [color-to-tui](https://github.com/uttarayan21/color-to-tui) — Parse hex colors to
|
|
`ratatui::style::Color`
|
|
* [rust-tui-template](https://github.com/ratatui-org/rust-tui-template) — A template for bootstrapping a
|
|
Rust TUI application with Tui-rs & crossterm
|
|
* [simple-tui-rs](https://github.com/pmsanford/simple-tui-rs) — A simple example tui-rs app
|
|
* [tui-builder](https://github.com/jkelleyrtp/tui-builder) — Batteries-included MVC framework for
|
|
Tui-rs + Crossterm apps
|
|
* [tui-clap](https://github.com/kegesch/tui-clap-rs) — Use clap-rs together with Tui-rs
|
|
* [tui-log](https://github.com/kegesch/tui-log-rs) — Example of how to use logging with Tui-rs
|
|
* [tui-logger](https://github.com/gin66/tui-logger) — Logger and Widget for Tui-rs
|
|
* [tui-realm](https://github.com/veeso/tui-realm) — Tui-rs framework to build stateful applications
|
|
with a React/Elm inspired approach
|
|
* [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) — Treeview component for
|
|
Tui-realm
|
|
* [tui-rs-tree-widgets](https://github.com/EdJoPaTo/tui-rs-tree-widget): Widget for tree data
|
|
structures.
|
|
* [tui-windows](https://github.com/markatk/tui-windows-rs) — Tui-rs abstraction to handle multiple
|
|
windows and their rendering
|
|
* [tui-textarea](https://github.com/rhysd/tui-textarea): Simple yet powerful multi-line text editor
|
|
widget supporting several key shortcuts, undo/redo, text search, etc.
|
|
* [tui-input](https://github.com/sayanarijit/tui-input): TUI input library supporting multiple
|
|
backends and tui-rs.
|
|
* [tui-term](https://github.com/a-kenji/tui-term): A pseudoterminal widget library
|
|
that enables the rendering of terminal applications as ratatui widgets.
|
|
|
|
## Apps
|
|
|
|
Check out the list of more than 50 [Apps using
|
|
`Ratatui`](https://github.com/ratatui-org/ratatui/wiki/Apps-using-Ratatui)!
|
|
|
|
## Alternatives
|
|
|
|
You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an alternative solution
|
|
to build text user interfaces in Rust.
|
|
|
|
## Contributors
|
|
|
|
[](https://github.com/ratatui-org/ratatui/graphs/contributors)
|
|
|
|
## Acknowledgments
|
|
|
|
Special thanks to [**Pavel Fomchenkov**](https://github.com/nawok) for his work in designing **an
|
|
awesome logo** for the ratatui project and ratatui-org organization.
|
|
|
|
## License
|
|
|
|
[MIT](./LICENSE)
|