mirror of
https://github.com/ratatui/ratatui.git
synced 2025-09-27 13:01:13 +00:00
171 lines
7.2 KiB
Markdown
171 lines
7.2 KiB
Markdown
<details>
|
||
<summary>Table of Contents</summary>
|
||
|
||
- [Quickstart](#quickstart)
|
||
- [Documentation](#documentation)
|
||
- [Templates](#templates)
|
||
- [Built with Ratatui](#built-with-ratatui)
|
||
- [Alternatives](#alternatives)
|
||
- [Contributing](#contributing)
|
||
- [Acknowledgements](#acknowledgements)
|
||
- [License](#license)
|
||
|
||
</details>
|
||
|
||
|
||
|
||
<div align="center">
|
||
|
||
[![Crate Badge]][Crate] [![Repo Badge]][Repo] [![Docs Badge]][Docs] [![License Badge]][License] \
|
||
[![CI Badge]][CI] [![Deps Badge]][Deps] [![Codecov Badge]][Codecov] [![Sponsors Badge]][Sponsors] \
|
||
[Ratatui Website] · [Docs] · [Widget Examples] · [App Examples] · [Changelog] \
|
||
[Breaking Changes] · [Contributing] · [Report a bug] · [Request a Feature]
|
||
|
||
</div>
|
||
|
||
[Ratatui][Ratatui Website] (_ˌræ.təˈtu.i_) is a Rust crate for cooking up terminal user interfaces
|
||
(TUIs). It provides a simple and flexible way to create text-based user interfaces in the terminal,
|
||
which can be used for command-line applications, dashboards, and other interactive console programs.
|
||
|
||
## Quickstart
|
||
|
||
Ratatui has [templates] available to help you get started quickly. You can use the
|
||
[`cargo-generate`] command to create a new project with Ratatui:
|
||
|
||
```shell
|
||
cargo install --locked cargo-generate
|
||
cargo generate ratatui/templates
|
||
```
|
||
|
||
Selecting the Hello World template produces the following application:
|
||
|
||
```rust
|
||
use color_eyre::Result;
|
||
use crossterm::event::{self, Event};
|
||
use ratatui::{DefaultTerminal, Frame};
|
||
|
||
fn main() -> Result<()> {
|
||
color_eyre::install()?;
|
||
let terminal = ratatui::init();
|
||
let result = run(terminal);
|
||
ratatui::restore();
|
||
result
|
||
}
|
||
|
||
fn run(mut terminal: DefaultTerminal) -> Result<()> {
|
||
loop {
|
||
terminal.draw(render)?;
|
||
if matches!(event::read()?, Event::Key(_)) {
|
||
break Ok(());
|
||
}
|
||
}
|
||
}
|
||
|
||
fn render(frame: &mut Frame) {
|
||
frame.render_widget("hello world", frame.area());
|
||
}
|
||
```
|
||
|
||
## Documentation
|
||
|
||
- [Docs] - the full API documentation for the library on docs.rs.
|
||
- [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials.
|
||
- [Ratatui Forum] - a place to ask questions and discuss the library.
|
||
- [Widget Examples] - a collection of examples that demonstrate how to use the library.
|
||
- [App Examples] - a collection of more complex examples that demonstrate how to build apps.
|
||
- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
|
||
- [Breaking Changes] - a list of breaking changes in the library.
|
||
|
||
You can also watch the [EuroRust 2024 talk] to learn about common concepts in Ratatui and what's
|
||
possible to build with it.
|
||
|
||
## Templates
|
||
|
||
If you're looking to get started quickly, you can use one of the available templates from the
|
||
[templates] repository using [`cargo-generate`]:
|
||
|
||
```shell
|
||
cargo generate ratatui/templates
|
||
```
|
||
|
||
## Built with Ratatui
|
||
|
||
[][awesome-ratatui]
|
||
|
||
Check out the [showcase] section of the website, or the [awesome-ratatui] repository for a curated
|
||
list of awesome apps and libraries built with Ratatui!
|
||
|
||
## Alternatives
|
||
|
||
- [Cursive](https://crates.io/crates/cursive) - a ncurses-based TUI library.
|
||
- [iocraft](https://crates.io/crates/iocraft) - a declarative TUI library.
|
||
|
||
## Contributing
|
||
|
||
[![Discord Badge]][Discord Server] [![Matrix Badge]][Matrix] [![Forum Badge]][Ratatui Forum]
|
||
|
||
Feel free to join our [Discord server](https://discord.gg/pMCEU9hNEj) for discussions and questions!
|
||
There is also a [Matrix](https://matrix.org/) bridge available at
|
||
[#ratatui:matrix.org](https://matrix.to/#/#ratatui:matrix.org). We have also recently launched the
|
||
[Ratatui Forum].
|
||
|
||
We rely on GitHub for [bugs][Report a bug] and [feature requests][Request a Feature].
|
||
|
||
Please make sure you read the [contributing](./CONTRIBUTING.md) guidelines before [creating a pull
|
||
request][Create a Pull Request].
|
||
|
||
## Acknowledgements
|
||
|
||
Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its development. None of
|
||
this could be possible without [Florian Dehau] who originally created [tui-rs] which inspired many
|
||
Rust TUIs.
|
||
|
||
Special thanks to [Pavel Fomchenkov] for his work in designing an awesome logo for the Ratatui
|
||
project and organization.
|
||
|
||
## License
|
||
|
||
This project is licensed under the [MIT License][License].
|
||
|
||
[Repo]: https://github.com/ratatui/ratatui
|
||
[Ratatui Website]: https://ratatui.rs/
|
||
[Ratatui Forum]: https://forum.ratatui.rs
|
||
[Docs]: https://docs.rs/ratatui
|
||
[Widget Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui-widgets/examples
|
||
[App Examples]: https://github.com/ratatui/ratatui/tree/main/examples
|
||
[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
|
||
[git-cliff]: https://git-cliff.org
|
||
[Conventional Commits]: https://www.conventionalcommits.org
|
||
[Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
|
||
[EuroRust 2024 talk]: https://www.youtube.com/watch?v=hWG51Mc1DlM
|
||
[Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
|
||
[Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
|
||
[Create a Pull Request]: https://github.com/ratatui/ratatui/compare
|
||
[Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
|
||
[Crate]: https://crates.io/crates/ratatui
|
||
[tui-rs]: https://crates.io/crates/tui
|
||
[Sponsors]: https://github.com/sponsors/ratatui
|
||
[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&color=E05D44
|
||
[Repo Badge]: https://img.shields.io/badge/repo-ratatui/ratatui-1370D3?style=flat-square&logo=github
|
||
[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
|
||
[CI Badge]: https://img.shields.io/github/actions/workflow/status/ratatui/ratatui/ci.yml?style=flat-square&logo=github
|
||
[CI]: https://github.com/ratatui/ratatui/actions/workflows/ci.yml
|
||
[Codecov Badge]: https://img.shields.io/codecov/c/github/ratatui/ratatui?logo=codecov&style=flat-square&token=BAQ8SOKEST&color=C43AC3
|
||
[Codecov]: https://app.codecov.io/gh/ratatui/ratatui
|
||
[Deps Badge]: https://deps.rs/repo/github/ratatui/ratatui/status.svg?path=ratatui&style=flat-square
|
||
[Deps]: https://deps.rs/repo/github/ratatui/ratatui?path=ratatui
|
||
[Discord Badge]: https://img.shields.io/discord/1070692720437383208?label=discord&logo=discord&style=flat-square&color=1370D3&logoColor=1370D3
|
||
[Discord Server]: https://discord.gg/pMCEU9hNEj
|
||
[Docs Badge]: https://img.shields.io/badge/docs-ratatui-1370D3?style=flat-square&logo=rust
|
||
[Matrix Badge]: https://img.shields.io/matrix/ratatui-general%3Amatrix.org?style=flat-square&logo=matrix&label=Matrix&color=C43AC3
|
||
[Matrix]: https://matrix.to/#/#ratatui:matrix.org
|
||
[Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
|
||
[Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
|
||
[templates]: https://github.com/ratatui/templates/
|
||
[showcase]: https://ratatui.rs/showcase/
|
||
[awesome-ratatui]: https://github.com/ratatui/awesome-ratatui
|
||
[Pavel Fomchenkov]: https://github.com/nawok
|
||
[Florian Dehau]: https://github.com/fdehau
|
||
[`cargo-generate`]: https://crates.io/crates/cargo-generate
|
||
[License]: ./LICENSE
|