# tui-realm: a React and Elm style framework for ratatui

> tui-realm sits on top of ratatui and gives terminal applications the structure web frameworks have, components with properties and state, a message and event system, update routines in the Elm sense, and a view that handles mounting, focus and event forwarding. The name is the explanation, since Realm stands for React and Elm.

**veeso/tui-realm** — 👑 A ratatui framework to build stateful applications with a React/Elm inspired approach 

- Repository: https://github.com/veeso/tui-realm
- Stars: 1,009 · Forks: 42
- Language: Rust
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/veeso-tui-realm

## The name explains the design

tui-realm is a framework for ratatui that simplifies the implementation of terminal user interfaces by adding the possibility of working with reusable components that have properties and states, as you would in React. The components then communicate with the UI engine through a system based on Messages and Events, which lets you write update routines the way Elm does.

The name is spelled out in the README, and it is the key to reading the code. Realm stands for React and Elm. React for the component model, with properties and state, and Elm for the update loop, where the state change is described rather than mutated in place.

The README is quick to admit that this is not a rendering library. It does not draw, it organises. ratatui draws, and tui-realm decides what should be drawn, what has changed and where the focus is.

The features list is the same argument in short form, and it is worth reading for the vocabulary it uses. The framework is event-driven, it is based on React and Elm, it removes boilerplate, it has quick setup, it manages focus and state in a single place, and it is easy to learn and adaptable to any use case.

The framework also ships with a standard library of components, and there are demos in the core examples and in the standard library examples, so the intended way to learn it is to read and run those.

## Components with properties and state

The core idea in the About section is that the components are organised inside the View, which manages mounting and unmounting, focus and event forwarding for you, and that the components communicate with the UI engine through Messages and Events.

Take those three responsibilities in turn, because they are the difference between tui-realm and raw ratatui. In a raw ratatui application, the render loop walks the state and draws it, the event loop reads keys and mutates state directly, and the focus is whatever your own bookkeeping says it is. Each of those is a decision the application makes, and each of them is a place where a large terminal application accumulates bugs.

In tui-realm, a component is mounted into the View, and the View owns the focus and the event routing. A component receives its input as events, decides what to do, and sends a message. The View forwards the messages, and the update routine is where the state change is described. That is a retained-mode architecture, and the trade is the usual one: you give up immediate-mode simplicity and gain a structure that scales with the size of the application.

The derive crate exists because of a specific pattern. tuirealm_derive is a helper derive library to derive Component for components which just pass those functions to an underlying component, which is the common case of wrapping a ratatui widget in something that participates in the focus and event system without adding behaviour of its own.

## The workspace, five crates and a version four line

The Get Started section describes the repository as a monorepo, and the crate list is the map.

The tuirealm crate is the core, containing all the basic functionality. The tui-realm-stdlib crate is the standard library, providing convenience wrappers for standard ratatui widgets, and it is the crate that turns the ordinary ratatui components into components the framework can mount and focus. The tuirealm_derive crate is the derive helper described above. And there are two component implementations, tui-realm-treeview for a tree component and tui-realm-textarea for a text area component.

The two component crates are worth a note, because they are the two widgets you would otherwise write yourself. A tree view is the structure behind a file browser, a settings tree or a package list, and a text area is the one that a terminal application needs for anything the user edits. Shipping them as separate crates keeps the core small and lets a user take the tree without the text area.

The workspace metadata is also telling about the project's maturity. The edition is 2024 and the minimum Rust version is 1.88, which is a recent toolchain floor, and the crates are versioned together on a 4 line, with the core, the standard library and the derive macro all at version 4 in the workspace dependencies. Versioning the family together means a user upgrades the whole set in one step, which is the right call for a framework where the crates depend on each other by path and version.

## The development workflow, and why just

The Development section is short and it says something about how the project is run. The repository uses just as the task runner, and all build, lint, format and test checks should go through the just recipes, because they encode the exact flags used by CI.

The four recipes shown are the ones a contributor needs:

```bash
just                          # list all recipes
just build_all                # build the workspace with all features
just test_all                 # run all tests with all features
just check_code               # rustfmt --check + clippy (CI-equivalent)
just publish_all              # publish all crates in dependency order
```

The insistence on the recipes is the point. A project where the local command and the CI command differ accumulates a class of problem where a change passes on one machine and fails on another, and encoding the flags in one place removes the possibility. check_code being described as CI-equivalent is the same idea stated as a promise.

publish_all deserves its own comment, because publishing a workspace of interdependent crates is a genuine chore. Publishing in dependency order is the requirement, and the recipe does it, so a maintainer does not have to remember which crate has to reach crates.io first.

The rest of the tooling is conventional and tidy, with a Justfile and a just/ directory holding the recipes, a rustfmt.toml for the formatting rules, a cliff.toml for the changelog generation that produces the CHANGELOG.md, and the usual GitHub workflows with a CI badge and Coveralls.

## Where tui-realm is the wrong choice

The first wrong-tool case is a small terminal program. If you are printing a table, drawing a progress bar or rendering a fixed view, ratatui alone is enough, and a component framework adds a layer of indirection between your code and the screen for no benefit. The framework earns its keep when the application has screens, focus that moves, and state that changes in more than one place.

The second is a team that prefers immediate mode. tui-realm is a retained-mode framework, which means the state is described and updated through messages, and the component tree is managed for you. An experienced ratatui developer often has a strong opinion about immediate mode being simpler for small programs, and that opinion is not wrong.

The third is a project that needs a widget the ecosystem does not have. The standard library covers the common ratatui widgets, and the two extra components are a tree view and a text area, and anything else is yours to write, which is fine but is work the framework does not save you from.

There is also the version line to consider. The crates are at version 4, and a 4.0.0 release followed a 3.3 line, so the major version boundary is recent, which means the migration notes matter and the ecosystem crates, if you depend on any, need to match.

## MIT, a 2026 release line, and a maintained dependency

The project is MIT licensed, with the LICENSE file at the repository root, and the default branch is main. The repository is not archived, and the last push was on 2026-07-29.

The release list shows v4.1.0 in May 2026, v4.0.0 in April 2026 and v3.3.0 in December 2025, so a major version in April and a minor release in May, with the 3.x line still being maintained through the same period. That is the pattern of a project that keeps its old line alive while the new one settles.

The dependency structure is the part to look at before choosing. The framework is built on ratatui, and the topics attached to the repository name crossterm and ratatui itself, along with console, gui, terminal, terminal-app, terminal-graphics and tui-framework. The crate downloads badge and the latest version badge point at the tui-realm package on crates.io, so the framework itself is a normal Cargo dependency, and the standard library, the derive macro and the two components are separate crates you add when you want them.

That structure is the practical summary of the project. The core is small and the extras are opt-in, and the documentation is on docs.rs with a get-started guide in the core crate's docs folder.

## Conclusion

Adopt tui-realm if you are building a stateful terminal application with ratatui and want the component and update model that a web developer would expect, rather than hand-rolling focus handling and event plumbing. Do not adopt it for a static dashboard or a simple form, where ratatui on its own is enough, and do not adopt it if your team is more comfortable with an immediate-mode approach, since this is a retained-mode framework with its own costs. Before you start, read the get-started guide in the core crate, and check the edition and toolchain requirements, since the workspace is on edition 2024 and needs Rust 1.88 or newer.

## FAQ

### What is tui-realm and what does it add to ratatui?

It is a framework for ratatui that lets you build terminal user interfaces from reusable components with properties and states, as in React, and that communicates with the UI engine through Messages and Events so you can write update routines as in Elm. The name comes from Realm standing for React and Elm.

### What crates make up the tui-realm project?

Five: tuirealm, the core crate with the basic functionality, tui-realm-stdlib with convenience wrappers for standard ratatui widgets, tuirealm_derive, a helper derive library for Component, tui-realm-treeview for a tree component, and tui-realm-textarea for a text area component.

### What does the View component in tui-realm do?

The components are organised inside the View, and the View manages mounting and unmounting, focus and event forwarding, so the application does not have to track focus and routing itself.

### How do I build and test tui-realm?

Through just, the task runner the project uses so that local commands match CI exactly. The recipes include just build_all, just test_all, just check_code, which is rustfmt --check plus clippy, and just publish_all, which publishes the crates in dependency order.

### What licence is tui-realm released under?

MIT, with the LICENSE file at the repository root. The workspace is on edition 2024 and needs Rust 1.88 or newer, the most recent release is v4.1.0 from 2026-05-02, and the last push was on 2026-07-29.

## Sources

- [Issues](https://github.com/veeso/tui-realm/issues)
- [License: MIT](https://github.com/veeso/tui-realm/blob/main/LICENSE)
- [README](https://github.com/veeso/tui-realm/blob/main/README.md)
- [Releases](https://github.com/veeso/tui-realm/releases)
- [veeso/tui-realm on GitHub](https://github.com/veeso/tui-realm)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/veeso-tui-realm