tui-realm

• tui-realm
  • About tui-realm 👑
  • Features 🎁
  • Get started 🏁
    • Add tui-realm to your Cargo.toml 🦀
      • Enabling other backends ⚠️
    • Create a tui-realm application 🪂
    • Run examples 🔍
  • Standard components library 🎨
  • Community components 🏘️
  • Guides 🎓
  • Documentation 📚
  • Apps using tui-realm 🚀
  • Support the developer ☕
  • Contributing and issues 🤝🏻
  • Changelog ⏳
  • License 📃

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 section.

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

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, termwiz

Add tui-realm to your Cargo.toml 🦀

If you want the default features, just add tuirealm with version:

tuirealm = "4"

otherwise you can specify the features you want to add:

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

Supported features are:

• derive (default): add the #[derive(Component)] proc macro to automatically implement Component for Component. Read more.
• serialize: add the serialize/deserialize trait implementation for KeyEvent and Key.
• crossterm: use the crossterm terminal & input backend
• termion: use the termion terminal & input backend
• termwiz: use the termwiz terminal & input backend
• async-ports: enable async (tokio) ports

Enabling other backends ⚠️

This library supports all backends supported by ratatui, which are crossterm(default), termion and termwiz. When deciding to use any other backend other than crossterm, default-features should be disabled to save on extra dependencies of unused backends.

❗ The two features can co-exist, even if it doesn't make too much sense. ❗ Backends other than crossterm may not have the best support.

Example using crossterm backend explicitly:

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

Example using the termion backend:

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

Example using the termwiz backend:

tuirealm = { version = "4", default-features = false, features = [ "derive", "termwiz" ] }

Create a tui-realm application 🪂

View how to implement a tui-realm application in the Get Started Guide.

Run examples 🔍

Interested in how tui-realm works and how the resulting code looks? Try the examples:

• demo: a simple example that shows basic tui-realm usage
• user-events: showcase using custom events
• inline-display: showcase how tui-realm can be used without requiring a alternate screen
• async-ports: showcase usage of async ports
• arbitrary-data: showcase usage of PropPayload::Any to send custom data across query and attr

Standard components library 🎨

tui-realm has a optional standard library called tui-realm-stdlib, which wraps common widgets from ratatui for usage in tui-realm. If you want to use it, just add the tui-realm-stdlib to your Cargo.toml dependencies.

Community components 🏘️

These components may not included in tui-realm or the stdlib, 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 A textarea/editor component developed by @veeso
• tui-realm-treeview A treeview component developed by @veeso
• tuirealm-orx-tree Another treeview component developed by @hasezoey

Want to add yours? Open an issue using the New app/component template 😄

Guides 🎓

• Get Started Guide
• Advanced concepts

Documentation 📚

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

Apps using tui-realm 🚀

• BugStalker
• cliflux
• csvs
• donmaze
• matrix-rust-sdk
• opencode-kanban
• paat
• termusic
• termscp
• tisq
• todotui
• tuifeed
• turdle
• quetty

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:

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