Home

Awesome

tui-realm

<p align="center"> <img src="docs/images/tui-realm.svg" alt="logo" width="256" height="256" /> </p> <p align="center">~ A ratatui framework inspired by Elm and React ~</p> <p align="center"> <a href="docs/en/get-started.md" target="_blank">Get started</a> ยท <a href="https://github.com/veeso/tui-realm-stdlib" target="_blank">Standard Library</a> ยท <a href="https://docs.rs/tuirealm" target="_blank">Documentation</a> </p> <p align="center">Developed by <a href="https://veeso.github.io/" target="_blank">@veeso</a></p> <p align="center">Current version: 2.0.3 (14/10/2024)</p> <p align="center"> <a href="https://opensource.org/licenses/MIT" ><img src="https://img.shields.io/badge/License-MIT-teal.svg" alt="License-MIT" /></a> <a href="https://github.com/veeso/tui-realm/stargazers" ><img src="https://img.shields.io/github/stars/veeso/tui-realm.svg?style=plain" alt="Repo stars" /></a> <a href="https://crates.io/crates/tuirealm" ><img src="https://img.shields.io/crates/d/tuirealm.svg" alt="Downloads counter" /></a> <a href="https://crates.io/crates/tuirealm" ><img src="https://img.shields.io/crates/v/tuirealm.svg" alt="Latest version" /></a> <a href="https://ko-fi.com/veeso"> <img src="https://img.shields.io/badge/donate-ko--fi-red" alt="Ko-fi" /></a> </p> <p align="center"> <a href="https://github.com/veeso/tui-realm/actions/workflows/ratatui_crossterm.yml" ><img src="https://github.com/veeso/tui-realm/actions/workflows/ratatui_crossterm.yml/badge.svg" alt="Ratatui-Crossterm CI" /></a> <a href="https://github.com/veeso/tui-realm/actions/workflows/ratatui_termion.yml" ><img src="https://github.com/veeso/tui-realm/actions/workflows/ratatui_termion.yml/badge.svg" alt="Ratatui-Termion CI" /></a> <a href="https://github.com/veeso/tui-realm/actions/workflows/crossterm-windows.yml" ><img src="https://github.com/veeso/tui-realm/actions/workflows/crossterm-windows.yml/badge.svg" alt="Crossterm CI (Windows)" /></a> <a href="https://coveralls.io/github/veeso/tui-realm" ><img src="https://coveralls.io/repos/github/veeso/tui-realm/badge.svg" alt="Coveralls" /></a> <a href="https://docs.rs/tuirealm" ><img src="https://docs.rs/tuirealm/badge.svg" alt="Docs" /></a> </p>

About tui-realm ๐Ÿ‘‘

tui-realm is a framework for 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.

Demo

See tui-realm in action in the Example or if you want to read more about tui-realm start reading the official guide HERE.

Features ๐ŸŽ


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:

tuirealm = "2"

otherwise you can specify the features you want to add:

tuirealm = { version = "2", default-features = false, features = [ "derive", "serialize", "termion" ] }

Supported features are:

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:

tuirealm = { version = "2", default-features = false, features = [ "derive", "crossterm" ]}

Example using the termion backend:

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.

Run examples ๐Ÿ”

Still confused about how tui-realm works? Don't worry, try with the examples:


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 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 ๐Ÿ’œ.

Want to add yours? Open an issue using the New app/component template ๐Ÿ˜„


Guides ๐ŸŽ“


Documentation ๐Ÿ“š

The developer documentation can be found on Rust Docs at https://docs.rs/tuirealm


Apps using tui-realm ๐Ÿš€

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 PayPal


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


Changelog โณ

View tui-realm's changelog HERE


License ๐Ÿ“ƒ

tui-realm is licensed under the MIT license.

You can read the entire license HERE