itsscb/ratatui
1
0
Fork 0
mirror of https://github.com/ratatui/ratatui.git synced 2025-09-28 13:31:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
ratatui/examples
History
Josh McKinney 2739391950
style: use Module imports_granularity (#1728) 
I was swayed by the arguments about this made by the compiler team In
<https://github.com/rust-lang/compiler-team/issues/750> and decided to
look at how this organization affects ratatui. I found this reduces the
number of lines across the codebase by about 350 and makes the imports
more readable and definitely more greppable as you usually only have
to read a single line. I've found in the past that maintaining imports
regularly leads to merge conflicts which have to be resolved by hand
and this change should reduce the likelihood of that happening.

Main change is in rustfmt.toml, and the rest is just the result of
running `cargo xtask format`.

While implementing this, cargo machete brings up that the various
backend crates are unused by the example crates.

The re-export of each backend crate under ratatui is to make it possible
for libs that rely on a specific version of ratatui to use the same
version of the backend crate. Apps in general should use the backend
crate directly rather than through ratatui as this is less confusing.

- Removes all usages of `ratatui::{crossterm, termion, termwiz}`` in the
  examples.
- Adds the backend crate to the dependencies of the examples that use
  the backend crate directly.
2025-03-19 16:48:02 -07:00
..
apps
style: use Module imports_granularity (#1728)
2025-03-19 16:48:02 -07:00
vhs
fix(examples): run the correct example for chart (#1679)
2025-02-18 13:44:29 +03:00
README.md
docs(examples): update app examples with tapes (#1673)
2025-02-11 13:18:06 -08:00

README.md

Examples

This folder contains examples that are more application focused. There are also widget examples in ratatui-widgets.

You can run these examples using:

cargo run -p example-name

This folder might use unreleased code. Consider viewing the examples in the latest branch instead of the main branch for code which is guaranteed to work with the released ratatui version.

Warning

There may be backwards incompatible changes in these examples, as they are designed to compile against the main branch.

There are a few workaround for this problem:

  • View the examples as they were when the latest version was release by selecting the tag that matches that version. E.g. https://github.com/ratatui/ratatui/tree/v0.26.1/examples.
  • If you're viewing this file on GitHub, there is a combo box at the top of this page which allows you to select any previous tagged version.
  • To view the code locally, checkout the tag. E.g. git switch --detach v0.26.1.
  • Use the latest [alpha version of Ratatui] in your app. These are released weekly on Saturdays.
  • Compile your code against the main branch either locally by adding e.g. path = "../ratatui" to the dependency, or remotely by adding git = "https://github.com/ratatui/ratatui"

For a list of unreleased breaking changes, see [BREAKING-CHANGES.md].

We don't keep the CHANGELOG updated with unreleased changes, check the git commit history or run git-cliff -u against a cloned version of this repository.

Design choices

The examples contain some opinionated choices in order to make it easier for newer rustaceans to easily be productive in creating applications:

  • Each example has an App struct, with methods that implement a main loop, handle events and drawing the UI.
  • We use color_eyre for handling errors and panics. See How to use color-eyre with Ratatui on the website for more information about this.
  • Common code is not extracted into a separate file. This makes each example self-contained and easy to read as a whole.

Demo

This is the original demo example from the main README. It is available for each of the backends. Source.

Demo

Demo2

This is the demo example from the main README and crate page. Source.

Demo2

Async GitHub

Shows how to fetch data from GitHub API asynchronously. Source.

Async GitHub demo

Calendar Explorer

Shows how to render a calendar with different styles. Source.

Calendar explorer demo

Canvas

Shows how to render a canvas with different shapes. Source.

Canvas demo

Chart

Shows how to render line, bar, and scatter charts. Source.

Chart demo

Color Explorer

Shows how to handle the supported colors. Source.

Color explorer demo

Colors-RGB demo

Shows the full range of RGB colors in an animation. Source.

Colors-RGB demo

Constraint Explorer

Shows how different constraints can be used to layout widgets. Source.

Constraint Explorer demo

Constraints

Shows different types of constraints. Source.

Constraints demo

Custom Widget

Shows how to create a custom widget that can be interacted with the mouse. Source.

Custom widget demo

Hyperlink

Shows how to render hyperlinks in a terminal using OSC 8. Source.

Hyperlink demo

Flex

Shows how to use the flex layouts. Source.

Flex demo

Hello World

Shows how to create a simple TUI with a text. Source.

Hello World demo

Gauge

Shows different types of gauges. Source.

Inline

Shows how to use the inlined viewport to render in a specific area of the screen. Source.

Inline demo

Input Form

Shows how to render a form with input fields. Source.

Modifiers

Shows different types of modifiers. Source.

Modifiers demo

Mouse Drawing

Shows how to handle mouse events. Source.

Minimal

Shows how to create a minimal application. Source.

Minimal demo

Panic

Shows how to handle panics. Source.

Panic demo

Popup

Shows how to handle popups. Source.

Popup demo

Scrollbar

Shows how to render different types of scrollbars. Source.

Scrollbar demo

Table

Shows how to create an interactive table. Source.

Table demo

Todo List

Shows how to create a simple todo list application. Source.

Todo List demo

Tracing

Shows how to use the tracing crate to log to a file. Source.

Tracing demo

User Input

Shows how to handle user input. Source. Source.

User input demo

Weather

Shows how to render weather data using barchart widget. Source.

WidgetRef Container

Shows how to use WidgetRef to store widgets in a container. Source.

Advanced Widget Implementation

Shows how to render the Widget trait in different ways.

Advanced widget impl demo

How to update these examples?

These gifs were created using VHS. Each example has a corresponding .tape file that holds instructions for how to generate the images. Note that the images themselves are stored in a separate images git branch to avoid bloating the main branch.