# tui-realm

logo

~ A ratatui framework inspired by Elm and React ~

Get started ยท Standard Library ยท Documentation

Developed by @veeso

Current version: 2.0.3 (14/10/2024)

License-MIT Repo stars Downloads counter Latest version Ko-fi

Ratatui-Crossterm CI Ratatui-Termion CI Crossterm CI (Windows) Coveralls Docs

--- - [tui-realm](#tui-realm) - [About tui-realm ๐Ÿ‘‘](#about-tui-realm-) - [Features ๐ŸŽ](#features-) - [Get started ๐Ÿ](#get-started-) - [Add tui-realm to your Cargo.toml ๐Ÿฆ€](#add-tui-realm-to-your-cargotoml-) - [Enabling other backends โš ๏ธ](#enabling-other-backends-๏ธ) - [Create a tui-realm application ๐Ÿช‚](#create-a-tui-realm-application-) - [Run examples ๐Ÿ”](#run-examples-) - [Standard components library ๐ŸŽจ](#standard-components-library-) - [Community components ๐Ÿ˜๏ธ](#community-components-๏ธ) - [Guides ๐ŸŽ“](#guides-) - [Documentation ๐Ÿ“š](#documentation-) - [Apps using tui-realm ๐Ÿš€](#apps-using-tui-realm-) - [Support the developer โ˜•](#support-the-developer-) - [Contributing and issues ๐Ÿค๐Ÿป](#contributing-and-issues-) - [Changelog โณ](#changelog-) - [License ๐Ÿ“ƒ](#license-) --- ## About tui-realm ๐Ÿ‘‘ tui-realm is a **framework** for **[ratatui](https://github.com/ratatui-org/ratatui)** to simplify the implementation of terminal user interfaces adding the possibility to work with re-usable components with properties and states, as you'd do in React. But that's not all: the components communicate with the ui engine via a system based on **Messages** and **Events**, providing you with the possibility to implement `update` routines as happens in Elm. In addition, the components are organized inside the **View**, which manages mounting/umounting, focus and event forwarding for you. And that also explains the reason of the name: **Realm stands for React and Elm**. tui-realm also comes with a standard library of components, which can be added to your dependencies, that you may find very useful. Don't worry, they are optional if you don't want to use them ๐Ÿ˜‰, just follow the guide in [get started](#get-started-). ![Demo](/docs/images/demo.gif) See tui-realm in action in the [Example](#run-examples-) or if you want to read more about tui-realm start reading the official guide [HERE](docs/en/get-started.md). ## Features ๐ŸŽ - โŒจ๏ธ **Event-driven** - โš›๏ธ Based on **React** and **Elm** - ๐Ÿฒ **Boilerplate** code - ๐Ÿš€ Quick-setup - ๐ŸŽฏ Single **focus** and **states** management - ๐Ÿ™‚ Easy to learn - ๐Ÿค– Adaptable to any use case --- ## Get started ๐Ÿ > โš ๏ธ Warning: currently tui-realm supports these backends: crossterm, termion ### Add tui-realm to your Cargo.toml ๐Ÿฆ€ If you want the default features, just add tuirealm 1.x version: ```toml tuirealm = "2" ``` otherwise you can specify the features you want to add: ```toml tuirealm = { version = "2", default-features = false, features = [ "derive", "serialize", "termion" ] } ``` Supported features are: - `derive` (*default*): add the `#[derive(MockComponent)]` proc macro to automatically implement `MockComponent` for `Component`. [Read more](https://github.com/veeso/tuirealm_derive). - `serialize`: add the serialize/deserialize trait implementation for `KeyEvent` and `Key`. - `crossterm`: use the [crossterm](https://github.com/crossterm-rs/crossterm) terminal backend - `termion`: use the [termion](https://github.com/redox-os/termion) terminal backend #### Enabling other backends โš ๏ธ This library supports two backends: `crossterm` and `termion`, and two high level terminal TUI libraries: `tui` and `ratatui`. Whenever you explicitly declare any of the TUI library or backend feature sets you should disable the crate's default features. > โ— The two features can co-exist, even if it doesn't make too much sense. Example using crossterm: ```toml tuirealm = { version = "2", default-features = false, features = [ "derive", "crossterm" ]} ``` Example using the termion backend: ```toml tuirealm = { version = "2", default-features = false, features = [ "derive", "termion" ] } ``` ### Create a tui-realm application ๐Ÿช‚ View how to implement a tui-realm application in the [related guide](/docs/en/get-started.md). ### Run examples ๐Ÿ” Still confused about how tui-realm works? Don't worry, try with the examples: - [demo](/examples/demo/demo.rs): a simple application which shows how tui-realm works ```sh cargo run --example demo ``` --- ## Standard components library ๐ŸŽจ Tui-realm comes with an optional standard library of components I thought would have been useful for most of the applications. If you want to use it, just add the [tui-realm-stdlib](https://github.com/veeso/tui-realm-stdlib) to your `Cargo.toml` dependencies. ## Community components ๐Ÿ˜๏ธ These components are not included in tui-realm, but have been developed by other users. I like advertising other's contents, so here you can find a list of components you may find useful for your next tui-realm project ๐Ÿ’œ. - [tui-realm-textarea](https://github.com/veeso/tui-realm-textarea) A textarea/editor component developed by [@veeso](https://github.com/veeso) - [tui-realm-treeview](https://github.com/veeso/tui-realm-treeview) A treeview component developed by [@veeso](https://github.com/veeso) Want to add yours? Open an issue using the `New app/component` template ๐Ÿ˜„ --- ## Guides ๐ŸŽ“ - [Get Started Guide](/docs/en/get-started.md) - [Advanced concepts](/docs/en/advanced.md) --- ## Documentation ๐Ÿ“š The developer documentation can be found on Rust Docs at --- ## Apps using tui-realm ๐Ÿš€ - [BugStalker](https://github.com/godzie44/BugStalker) - [cliflux](https://github.com/spencerwi/cliflux) - [donmaze](https://github.com/veeso/donmaze) - [matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk) - [paat](https://github.com/ebakoba/paat) - [termusic](https://github.com/tramhao/termusic) - [termscp](https://github.com/veeso/termscp) - [tisq](https://crates.io/crates/tisq) - [todotui](https://github.com/newfla/todotui) - [tuifeed](https://github.com/veeso/tuifeed) - [turdle](https://crates.io/crates/turdle) Want to add yours? Open an issue using the `New app/component` template ๐Ÿ˜„ --- ## Support the developer โ˜• If you like tui-realm and you're grateful for the work I've done, please consider a little donation ๐Ÿฅณ You can make a donation with one of these platforms: [![ko-fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/veeso) [![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white)](https://www.paypal.me/chrisintin) --- ## Contributing and issues ๐Ÿค๐Ÿป Contributions, bug reports, new features and questions are welcome! ๐Ÿ˜‰ If you have any question or concern, or you want to suggest a new feature, or you want just want to improve tui-realm, feel free to open an issue or a PR. Please follow [our contributing guidelines](CONTRIBUTING.md) --- ## Changelog โณ View tui-realm's changelog [HERE](CHANGELOG.md) --- ## License ๐Ÿ“ƒ tui-realm is licensed under the MIT license. You can read the entire license [HERE](LICENSE)