Compare commits

...

3 Commits

Author SHA1 Message Date
Orhun Parmaksız
a6d580bc96 fix(examples): run the correct example for chart 2025-02-18 09:40:04 +03:00
Orhun Parmaksız
392b28c194 chore(examples): remove examples dir from ratatui 2025-02-12 00:08:56 +03:00
Orhun Parmaksız
5814c7c395 docs(examples): update app examples with tapes 2025-02-12 00:06:48 +03:00
43 changed files with 288 additions and 732 deletions

View File

@@ -1,10 +1,9 @@
# Examples
This folder contains examples that are more app focused. There are also other examples in example
folders under each crate folder e.g. [ratatui examples], [ratatui-widgets examples].
This folder contains examples that are more application focused.
There are also [widget examples] in `ratatui-widgets`.
[ratatui examples]: ../ratatui/examples
[ratatui-widgets examples]: ../ratatui-widgets/examples
[widget examples]: ../ratatui-widgets/examples
You can run these examples using:
@@ -36,100 +35,238 @@ of the `main` branch for code which is guaranteed to work with the released rata
> 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.
[How to use color-eyre with Ratatui]: https://ratatui.rs/recipes/apps/color-eyre/
## Demo
This is the original demo example from the main README. It is available for each of the backends.
[Source](./apps/demo/).
![Demo](https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true)
![Demo](demo.gif)
## Demo2
This is the demo example from the main README and crate page. [Source](./apps/demo2/).
![Demo2](https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true)
![Demo2](demo2.gif)
## Async GitHub demo
## Async GitHub
Shows how to fetch data from GitHub API asynchronously. [Source](./apps/async-github/).
## Calendar explorer demo
![Async GitHub demo][async-github.gif]
## Calendar Explorer
Shows how to render a calendar with different styles. [Source](./apps/calendar-explorer/).
## Canvas demo
![Calendar explorer demo][calendar-explorer.gif]
## Canvas
Shows how to render a canvas with different shapes. [Source](./apps/canvas/).
![Canvas demo][canvas.gif]
## Chart
Shows how to render line, bar, and scatter charts. [Source](./apps/chart/).
![Chart demo][chart.gif]
## Color Explorer
Shows how to handle the supported colors. [Source](./apps/color-explorer/).
![Color explorer demo][color-explorer.gif]
## Colors-RGB demo
This example shows the full range of RGB colors in an animation. [Source](./apps/colors-rgb/).
Shows the full range of RGB colors in an animation. [Source](./apps/colors-rgb/).
## Constraint Explorer demo
![Colors-RGB demo][colors-rgb.gif]
This interactive example shows how different constraints can be used to layout widgets. [Source](./apps/constraint-explorer/).
## Constraint Explorer
## Constraints demo
Shows how different constraints can be used to layout widgets. [Source](./apps/constraint-explorer/).
This example shows different types of constraints. [Source](./apps/constraints/).
![Constraint Explorer demo][constraint-explorer.gif]
## Custom widget demo
## Constraints
This example shows how to create a custom widget that can be interacted with the mouse. [Source](./apps/custom-widget/).
Shows different types of constraints. [Source](./apps/constraints/).
## Hyperlink demo
![Constraints demo][constraints.gif]
## Custom Widget
Shows how to create a custom widget that can be interacted with the mouse. [Source](./apps/custom-widget/).
![Custom widget demo][custom-widget.gif]
## Hyperlink
Shows how to render hyperlinks in a terminal using [OSC
8](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). [Source](./apps/hyperlink/).
## Flex demo
![Hyperlink demo][hyperlink.gif]
This interactive example shows how to use the flex layouts. [Source](./apps/flex/).
## Flex
## Hello World demo
Shows how to use the flex layouts. [Source](./apps/flex/).
This example shows how to create a simple TUI with a text. [Source](./apps/hello-world/).
![Flex demo][flex.gif]
## Gauge demo
## Hello World
This example shows different types of gauges. [Source](./apps/gauge/).
Shows how to create a simple TUI with a text. [Source](./apps/hello-world/).
## Inline demo
![Hello World demo][hello-world.gif]
## Gauge
Shows different types of gauges. [Source](./apps/gauge/).
## Inline
Shows how to use the inlined viewport to render in a specific area of the screen. [Source](./apps/inline/).
## Input form
![Inline demo][inline.gif]
## Input Form
Shows how to render a form with input fields. [Source](./apps/input-form/).
## Todo List demo
Shows how to create a simple todo list application. [Source](./apps/todo-list/).
## Modifiers demo
## Modifiers
Shows different types of modifiers. [Source](./apps/modifiers/).
## Mouse Drawing demo
![Modifiers demo][modifiers.gif]
## Mouse Drawing
Shows how to handle mouse events. [Source](./apps/mouse-drawing/).
## Minimal demo
## Minimal
Shows how to create a minimal application. [Source](./apps/minimal/).
## Scrollbar demo
![Minimal demo][minimal.gif]
## Panic
Shows how to handle panics. [Source](./apps/panic/).
![Panic demo][panic.gif]
## Popup
Shows how to handle popups. [Source](./apps/popup/).
![Popup demo][popup.gif]
## Scrollbar
Shows how to render different types of scrollbars. [Source](./apps/scrollbar/).
## User input demo
![Scrollbar demo][scrollbar.gif]
Shows how to handle user input. [Source](./apps/user-input/).
## Table
## Weather demo
Shows how to create an interactive table. [Source](./apps/table/).
![Table demo][table.gif]
## Todo List
Shows how to create a simple todo list application. [Source](./apps/todo-list/).
![Todo List demo][todo-list.gif]
## Tracing
Shows how to use the [tracing](https://crates.io/crates/tracing) crate to log to a file. [Source](./apps/tracing/).
![Tracing demo][tracing.gif]
## User Input
Shows how to handle user input. [Source](./apps/user-input/). [Source](./apps/user-input/).
![User input demo][user-input.gif]
## Weather
Shows how to render weather data using barchart widget. [Source](./apps/weather/).
## WidgetRef Container demo
## WidgetRef Container
Shows how to use [`WidgetRef`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.WidgetRef.html) to store widgets in a container. [Source](./apps/widget-ref-container/).
## Advanced Widget Implementation
Shows how to render the `Widget` trait in different ways.
![Advanced widget impl demo][advanced-widget-impl.gif]
---
<details>
<summary>How to update these examples?</summary>
These gifs were created using [VHS](https://github.com/charmbracelet/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.
<!--
Links to images to make them easier to update in bulk. Use the following script to update and upload
the examples to the images branch. (Requires push access to the branch).
```shell
vhs/generate.bash
```
-->
</details>
[advanced-widget-impl.gif]: https://github.com/ratatui/ratatui/blob/images/examples/advanced-widget-impl.gif?raw=true
[async-github.gif]: https://github.com/ratatui/ratatui/blob/images/examples/async-github.gif?raw=true
[calendar-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/calendar-explorer.gif?raw=true
[canvas.gif]: https://github.com/ratatui/ratatui/blob/images/examples/canvas.gif?raw=true
[chart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/chart.gif?raw=true
[color-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/color-explorer.gif?raw=true
[colors-rgb.gif]: https://github.com/ratatui/ratatui/blob/images/examples/colors-rgb.gif?raw=true
[constraint-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
[constraints.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraints.gif?raw=true
[custom-widget.gif]: https://github.com/ratatui/ratatui/blob/images/examples/custom-widget.gif?raw=true
[demo2-destroy.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2-destroy.gif?raw=true
[demo2-social.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2-social.gif?raw=true
[demo2.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo2.gif?raw=true
[demo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true
[flex.gif]: https://github.com/ratatui/ratatui/blob/images/examples/flex.gif?raw=true
[hello-world.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hello-world.gif?raw=true
[hyperlink.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hyperlink.gif?raw=true
[inline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/inline.gif?raw=true
[minimal.gif]: https://github.com/ratatui/ratatui/blob/images/examples/minimal.gif?raw=true
[modifiers.gif]: https://github.com/ratatui/ratatui/blob/images/examples/modifiers.gif?raw=true
[panic.gif]: https://github.com/ratatui/ratatui/blob/images/examples/panic.gif?raw=true
[popup.gif]: https://github.com/ratatui/ratatui/blob/images/examples/popup.gif?raw=true
[scrollbar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/scrollbar.gif?raw=true
[table.gif]: https://github.com/ratatui/ratatui/blob/images/examples/table.gif?raw=true
[todo-list.gif]: https://github.com/ratatui/ratatui/blob/images/examples/todo-list.gif?raw=true
[tracing.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tracing.gif?raw=true
[user-input.gif]: https://github.com/ratatui/ratatui/blob/images/examples/user-input.gif?raw=true

View File

@@ -1,6 +1,6 @@
# Popup demo
This example shows how to render line, bar, and scatter charts.
This example shows how to handle popups.
To run this demo:

View File

@@ -0,0 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/vhs/advanced-widget-impl.tape`
Output "target/advanced-widget-impl.gif"
Set Theme "Aardvark Blue"
Set Width 760
Set Height 260
Hide
Type "cargo run -p advanced-widget-impl"
Enter
Sleep 2s
Show
Sleep 5s

View File

@@ -0,0 +1,16 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/vhs/async-github.tape`
Output "target/async-github.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Hide
Type "cargo run -p async-github"
Enter
Sleep 1s
Show
Sleep 1s
Set TypingSpeed 0.5s
Down 3
Up
Sleep 1s

View File

@@ -0,0 +1,19 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/vhs/calendar-explorer.tape`
Output "target/calendar-explorer.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 800
Hide
Type "cargo run -p calendar-explorer"
Enter
Sleep 3s
Show
Set TypingSpeed 1s
Type "s"
Type "s"
Type "s"
Type 'n'
Type 'p'
Down 5
Right 5

View File

@@ -1,12 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/canvas.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/canvas.tape`
Output "target/canvas.gif"
Set Theme "Aardvark Blue"
Set FontSize 12
Set Width 1200
Set Height 800
Hide
Type "cargo run --example=canvas --features=crossterm"
Type "cargo run -p canvas"
Enter
Sleep 2s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/chart.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/chart.tape`
Output "target/chart.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 800
Hide
Type "cargo run --example=chart --features=crossterm"
Type "cargo run -p chart"
Enter
Sleep 1s
Show

View File

@@ -1,12 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/layout.tape`
Output "target/layout.gif"
# To run this script, install vhs and run `vhs ./examples/vhs/color-explorer.tape`
Output "target/color-explorer.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1410
Hide
Type "cargo run --example=layout --features=crossterm"
Type "cargo run -p color-explorer"
Enter
Sleep 1s
Show
Sleep 2s
Show
Sleep 1s

View File

@@ -1,9 +1,9 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/colors_rgb.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/colors-rgb.tape`
# note that this script sometimes results in the gif having screen tearing
# issues. I'm not sure why, but it's not a problem with the library.
Output "target/colors_rgb.gif"
Output "target/colors-rgb.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1200
@@ -13,9 +13,9 @@ Set Framerate 60
Set CursorBlink false
Hide
Type "cargo run --example=colors_rgb --features=crossterm --release"
Type "cargo run -p colors-rgb"
Enter
Sleep 2s
# Screenshot "target/colors_rgb.png"
# Screenshot "target/colors-rgb.png"
Show
Sleep 10s

View File

@@ -1,12 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/constraint-explorer.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/constraint-explorer.tape`
Output "target/constraint-explorer.gif"
Set Theme "Aardvark Blue"
Set FontSize 18
Set Width 1200
Set Height 950
Hide
Type "cargo run --example=constraint-explorer --features=crossterm"
Type "cargo run -p constraint-explorer"
Enter
Sleep 2s
Show

View File

@@ -1,12 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/constraints.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/constraints.tape`
Output "target/constraints.gif"
Set Theme "Aardvark Blue"
Set FontSize 18
Set Width 1200
Set Height 700
Hide
Type "cargo run --example=constraints --features=crossterm"
Type "cargo run -p constraints"
Enter
Sleep 2s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/custom_widget.tape`
Output "target/custom_widget.gif"
# To run this script, install vhs and run `vhs ./examples/vhs/custom-widget.tape`
Output "target/custom-widget.gif"
Set Theme "Aardvark Blue"
Set Width 760
Set Height 260
Hide
Type "cargo run --example=custom_widget --features=crossterm"
Type "cargo run -p custom-widget"
Enter
Sleep 2s
Show

View File

@@ -1,12 +1,12 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/demo.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/demo.tape`
Output "target/demo.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1200
Set PlaybackSpeed 0.5
Hide
Type "cargo run --example demo"
Type "cargo run -p demo"
Enter
Sleep 2s
Show

View File

@@ -1,5 +1,5 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/demo2-destroy.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/demo2-destroy.tape`
# NOTE: Requires VHS 0.6.1 or later for Screenshot support
Output "target/demo2-destroy.gif"
Set Theme "Aardvark Blue"
@@ -10,7 +10,7 @@ Set Width 1120
Set Height 480
Set Padding 0
Hide
Type "cargo run --example demo2 --features crossterm,palette,widget-calendar"
Type "cargo run -p demo2"
Enter
Sleep 2s
Show

View File

@@ -1,5 +1,5 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/demo2-social.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/demo2-social.tape`
Output "target/demo2-social.gif"
Set Theme "Aardvark Blue"
@@ -9,7 +9,7 @@ Set Width 1280
Set Height 640
Set Padding 80
Hide
Type "cargo run --example demo2 --features crossterm,widget-calendar"
Type "cargo run -p demo2"
Enter
Sleep 2s
Show

View File

@@ -1,5 +1,5 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/demo2.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/demo2.tape`
# NOTE: Requires VHS 0.6.1 or later for Screenshot support
Output "target/demo2.gif"
Set Theme "Aardvark Blue"
@@ -10,7 +10,7 @@ Set Width 1120
Set Height 480
Set Padding 0
Hide
Type "cargo run --example demo2 --features crossterm,widget-calendar"
Type "cargo run -p demo2"
Enter
Sleep 2s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/flex.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/flex.tape`
Output "target/flex.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1410
Hide
Type "cargo run --example=flex --features=crossterm"
Type "cargo run -p flex"
Enter
Sleep 2s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/gauge.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/gauge.tape`
Output "target/gauge.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 850
Hide
Type "cargo run --example=gauge --features=crossterm"
Type "cargo run -p gauge"
Enter
Sleep 2s
Show

View File

@@ -7,7 +7,7 @@
# - git: https://git-scm.com/
# - vhs: https://github.com/charmbracelet/vhs - currently this needs to be installed from the
# main branch, as the latest release doesn't support the theme we use or the Screenshot
# command. Install using `go install github.com/charmbracelet/vhs@main``
# command. Install using `go install github.com/charmbracelet/vhs@main`
# - go: https://golang.org/doc/install
# - ttyd: https://github.com/tsl0922/ttyd
@@ -23,15 +23,18 @@ set -o pipefail
# set -o xtrace
# ensure that running each example doesn't have to wait for the build
cargo build --examples --features=crossterm,all-widgets
for app in *; do
cargo build -p "$app"
done
for tape_path in examples/vhs/*.tape; do
tape_file=${tape_path/examples\/vhs\//} # strip the examples/vhs/ prefix
gif_file=${tape_file/.tape/.gif} # replace the .tape suffix with .gif
~/go/bin/vhs $tape_path --quiet
~/go/bin/vhs "$tape_path" --quiet
# this can be pasted into the examples README.md
echo "[${gif_file}]: https://github.com/ratatui/ratatui/blob/images/examples/${gif_file}?raw=true"
done
git switch images
git pull --rebase upstream images
cp target/*.gif examples/

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/hello_world.tape`
Output "target/hello_world.gif"
# To run this script, install vhs and run `vhs ./examples/vhs/hello-world.tape`
Output "target/hello-world.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 200
Hide
Type "cargo run --example=hello_world --features=crossterm"
Type "cargo run -p hello-world"
Enter
Sleep 1s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/hyperlink.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/hyperlink.tape`
Output "target/hyperlink.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 200
Hide
Type "cargo run --example=hyperlink --features=crossterm,unstable-widget-ref"
Type "cargo run -p hyperlink"
Enter
Sleep 3s
Show

View File

@@ -1,9 +1,9 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/inline.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/inline.tape`
Output "target/inline.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Type "cargo run --example=inline --features=crossterm"
Type "cargo run -p inline"
Enter
Sleep 20s

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/minimal.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/minimal.tape`
Output "target/minimal.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 200
Hide
Type "cargo run --example=minimal --features=crossterm"
Type "cargo run -p minimal"
Enter
Sleep 1s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/modifiers.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/modifiers.tape`
Output "target/modifiers.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1460
Hide
Type "cargo run --example=modifiers --features=crossterm"
Type "cargo run -p modifiers"
Enter
Sleep 2s
Show

View File

@@ -1,17 +1,17 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/panic.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/panic.tape`
Output "target/panic.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Type "cargo run --example=panic --features=crossterm"
Type "cargo run -p panic"
Enter
Sleep 5s
Type p
Sleep 2s
Type reset
Enter
Type "cargo run --example=panic --features=crossterm"
Type "cargo run -p panic"
Enter
Sleep 2s
Type e

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/popup.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/popup.tape`
Output "target/popup.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Hide
Type "cargo run --example=popup --features=crossterm"
Type "cargo run -p popup"
Enter
Sleep 1s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/scrollbar.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/scrollbar.tape`
Output "target/scrollbar.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1200
Hide
Type "cargo run --example=scrollbar --features=crossterm"
Type "cargo run -p scrollbar"
Enter
Sleep 1s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/table.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/table.tape`
Output "target/table.gif"
Set Theme "Aardvark Blue"
Set Width 1400
Set Height 768
Hide
Type "cargo run --example=table --features=crossterm"
Type "cargo run -p table"
Enter
Sleep 1s
Show

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/list.tape`
Output "target/list.gif"
# To run this script, install vhs and run `vhs ./examples/vhs/todo-list.tape`
Output "target/todo-list.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 612
Hide
Type "cargo run --example=list --features=crossterm"
Type "cargo run -p todo-list"
Enter
Sleep 10s
Show

View File

@@ -1,10 +1,10 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/tracing.tape`
# To run this script, install vhs and run `vhs ./examples/vhs/tracing.tape`
Output "target/tracing.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 800
Type "RUST_LOG=trace cargo run --example=tracing" Enter
Type"RUST_LOG=trace cargo run -p tracing" Enter
Sleep 1s
Type @100ms "jjjjq"
Sleep 1s

View File

@@ -1,11 +1,11 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/user_input.tape`
Output "target/user_input.gif"
# To run this script, install vhs and run `vhs ./examples/vhs/user-input.tape`
Output "target/user-input.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Hide
Type "cargo run --example=user_input --features=crossterm"
Type "cargo run -p user-input"
Enter
Sleep 1s
Show

View File

@@ -1,467 +0,0 @@
# Examples
This folder might use unreleased code. View the examples for the latest release instead.
> [!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.
Not every example has been updated with all these points in mind yet, however over time they will
be. None of the above choices are strictly necessary for Ratatui apps, but these choices make
examples easier to run, maintain and explain. These choices are designed to help newer users fall
into the pit of success when incorporating example code into their own apps. We may also eventually
move some of these design choices into the core of Ratatui to simplify apps.
[How to use color-eyre with Ratatui]: https://ratatui.rs/how-to/develop-apps/color_eyre/
## Demo
This is the previous demo example from the main README. It is available for each of the backends. Source:
[demo.rs](./demo/).
```shell
cargo run --example=demo --features=crossterm
cargo run --example=demo --no-default-features --features=termion
cargo run --example=demo --no-default-features --features=termwiz
```
![Demo][demo.gif]
## Hello World
This is a pretty boring example, but it contains some good documentation
on writing tui apps. Source: [hello_world.rs](./hello_world.rs).
```shell
cargo run --example=hello_world --features=crossterm
```
![Hello World][hello_world.gif]
## Barchart
Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
widget. Source: [barchart.rs](./barchart.rs).
```shell
cargo run --example=barchart --features=crossterm
```
![Barchart][barchart.gif]
## Barchart (Grouped)
Demonstrates the [`BarChart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html)
widget with groups. Source: [barchart-grouped.rs](./barchart-grouped.rs).
```shell
cargo run --example=barchart-grouped --features=crossterm
```
![Barchart Grouped][barchart-grouped.gif]
## Block
Demonstrates the [`Block`](https://docs.rs/ratatui/latest/ratatui/widgets/block/struct.Block.html)
widget. Source: [block.rs](./block.rs).
```shell
cargo run --example=block --features=crossterm
```
![Block][block.gif]
## Calendar
Demonstrates the [`Calendar`](https://docs.rs/ratatui/latest/ratatui/widgets/calendar/index.html)
widget. Source: [calendar.rs](./calendar.rs).
```shell
cargo run --example=calendar --features="crossterm widget-calendar"
```
![Calendar][calendar.gif]
## Canvas
Demonstrates the [`Canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) widget
and related shapes in the
[`canvas`](https://docs.rs/ratatui/latest/ratatui/widgets/canvas/index.html) module. Source:
[canvas.rs](./canvas.rs).
```shell
cargo run --example=canvas --features=crossterm
```
![Canvas][canvas.gif]
## Chart
Demonstrates the [`Chart`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Chart.html) widget.
Source: [chart.rs](./chart.rs).
```shell
cargo run --example=chart --features=crossterm
```
![Chart][chart.gif]
## Colors
Demonstrates the available [`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html)
options. These can be used in any style field. Source: [colors.rs](./colors.rs).
```shell
cargo run --example=colors --features=crossterm
```
![Colors][colors.gif]
## Colors (RGB)
Demonstrates the available RGB
[`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) options. These can be used
in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). Uses a half block technique to render
two square-ish pixels in the space of a single rectangular terminal cell.
```shell
cargo run --example=colors_rgb --features=crossterm
```
Note: VHs renders full screen animations poorly, so this is a screen capture rather than the output
of the VHS tape.
<https://github.com/ratatui/ratatui/assets/381361/485e775a-e0b5-4133-899b-1e8aeb56e774>
## Constraint Explorer
Demonstrates the behaviour of each
[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) option with
respect to each other across different `Flex` modes.
```shell
cargo run --example=constraint-explorer --features=crossterm
```
![Constraint Explorer][constraint-explorer.gif]
## Constraints
Demonstrates how to use
[`Constraint`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html) options for
defining layout element sizes.
![Constraints][constraints.gif]
```shell
cargo run --example=constraints --features=crossterm
```
## Custom Widget
Demonstrates how to implement the
[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Also shows mouse
interaction. Source: [custom_widget.rs](./custom_widget.rs).
```shell
cargo run --example=custom_widget --features=crossterm
```
![Custom Widget][custom_widget.gif]
## Gauge
Demonstrates the [`Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html) widget.
Source: [gauge.rs](./gauge.rs).
```shell
cargo run --example=gauge --features=crossterm
```
![Gauge][gauge.gif]
## Flex
Demonstrates the different [`Flex`](https://docs.rs/ratatui/latest/ratatui/layout/enum.Flex.html)
modes for controlling layout space distribution.
```shell
cargo run --example=flex --features=crossterm
```
![Flex][flex.gif]
## Line Gauge
Demonstrates the [`Line
Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.LineGauge.html) widget. Source:
[line_gauge.rs](./line_gauge.rs).
```shell
cargo run --example=line_gauge --features=crossterm
```
![LineGauge][line_gauge.gif]
## Hyperlink
Demonstrates how to use OSC 8 to create hyperlinks in the terminal.
```shell
cargo run --example=hyperlink --features="crossterm unstable-widget-ref"
```
![Hyperlink][hyperlink.gif]
## Inline
Demonstrates how to use the
[`Inline`](https://docs.rs/ratatui/latest/ratatui/terminal/enum.Viewport.html#variant.Inline)
Viewport mode for ratatui apps. Source: [inline.rs](./inline.rs).
```shell
cargo run --example=inline --features=crossterm
```
![Inline][inline.gif]
## Layout
Demonstrates the [`Layout`](https://docs.rs/ratatui/latest/ratatui/layout/struct.Layout.html) and
interaction between each constraint. Source: [layout.rs](./layout.rs).
```shell
cargo run --example=layout --features=crossterm
```
![Layout][layout.gif]
## List
Demonstrates the [`List`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.List.html) widget.
Source: [list.rs](./list.rs).
```shell
cargo run --example=list --features=crossterm
```
![List][list.gif]
## Modifiers
Demonstrates the style
[`Modifiers`](https://docs.rs/ratatui/latest/ratatui/style/struct.Modifier.html). Source:
[modifiers.rs](./modifiers.rs).
```shell
cargo run --example=modifiers --features=crossterm
```
![Modifiers][modifiers.gif]
## Minimal
Demonstrates how to create a minimal `Hello World!` program.
```shell
cargo run --example=minimal --features=crossterm
```
![Minimal][minimal.gif]
## Panic
Demonstrates how to handle panics by ensuring that panic messages are written correctly to the
screen. Source: [panic.rs](./panic.rs).
```shell
cargo run --example=panic --features=crossterm
```
![Panic][panic.gif]
## Paragraph
Demonstrates the [`Paragraph`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Paragraph.html)
widget. Source: [paragraph.rs](./paragraph.rs)
```shell
cargo run --example=paragraph --features=crossterm
```
![Paragraph][paragraph.gif]
## Popup
Demonstrates how to render a widget over the top of previously rendered widgets using the
[`Clear`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Clear.html) widget. Source:
[popup.rs](./popup.rs).
>
```shell
cargo run --example=popup --features=crossterm
```
![Popup][popup.gif]
## Ratatui-logo
A fun example of using half blocks to render graphics Source:
[ratatui-logo.rs](./ratatui-logo.rs).
>
```shell
cargo run --example=ratatui-logo --features=crossterm
```
![Ratatui Logo][ratatui-logo.gif]
## Scrollbar
Demonstrates the [`Scrollbar`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Scrollbar.html)
widget. Source: [scrollbar.rs](./scrollbar.rs).
```shell
cargo run --example=scrollbar --features=crossterm
```
![Scrollbar][scrollbar.gif]
## Sparkline
Demonstrates the [`Sparkline`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html)
widget. Source: [sparkline.rs](./sparkline.rs).
```shell
cargo run --example=sparkline --features=crossterm
```
![Sparkline][sparkline.gif]
## Table
Demonstrates the [`Table`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html) widget.
Source: [table.rs](./table.rs).
```shell
cargo run --example=table --features=crossterm
```
![Table][table.gif]
## Tabs
Demonstrates the [`Tabs`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html) widget.
Source: [tabs.rs](./tabs.rs).
```shell
cargo run --example=tabs --features=crossterm
```
![Tabs][tabs.gif]
## Tracing
Demonstrates how to use the [tracing crate](https://crates.io/crates/tracing) for logging. Creates
a file named `tracing.log` in the current directory.
```shell
cargo run --example=tracing --features=crossterm
```
![Tracing][tracing.gif]
## User Input
Demonstrates one approach to accepting user input. Source [user_input.rs](./user_input.rs).
> [!NOTE]
> Consider using [`tui-textarea`](https://crates.io/crates/tui-textarea) or
> [`tui-input`](https://crates.io/crates/tui-input) crates for more functional text entry UIs.
```shell
cargo run --example=user_input --features=crossterm
```
![User Input][user_input.gif]
## How to update these examples
These gifs were created using [VHS](https://github.com/charmbracelet/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
repository.
<!--
Links to images to make them easier to update in bulk. Use the following script to update and upload
the examples to the images branch. (Requires push access to the branch).
```shell
examples/vhs/generate.bash
```
-->
[barchart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart.gif?raw=true
[barchart-grouped.gif]: https://github.com/ratatui/ratatui/blob/images/examples/barchart-grouped.gif?raw=true
[block.gif]: https://github.com/ratatui/ratatui/blob/images/examples/block.gif?raw=true
[calendar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/calendar.gif?raw=true
[canvas.gif]: https://github.com/ratatui/ratatui/blob/images/examples/canvas.gif?raw=true
[chart.gif]: https://github.com/ratatui/ratatui/blob/images/examples/chart.gif?raw=true
[colors.gif]: https://github.com/ratatui/ratatui/blob/images/examples/colors.gif?raw=true
[constraint-explorer.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraint-explorer.gif?raw=true
[constraints.gif]: https://github.com/ratatui/ratatui/blob/images/examples/constraints.gif?raw=true
[custom_widget.gif]: https://github.com/ratatui/ratatui/blob/images/examples/custom_widget.gif?raw=true
[demo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/demo.gif?raw=true
[flex.gif]: https://github.com/ratatui/ratatui/blob/images/examples/flex.gif?raw=true
[gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/gauge.gif?raw=true
[hello_world.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hello_world.gif?raw=true
[hyperlink.gif]: https://github.com/ratatui/ratatui/blob/images/examples/hyperlink.gif?raw=true
[inline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/inline.gif?raw=true
[layout.gif]: https://github.com/ratatui/ratatui/blob/images/examples/layout.gif?raw=true
[list.gif]: https://github.com/ratatui/ratatui/blob/images/examples/list.gif?raw=true
[line_gauge.gif]: https://github.com/ratatui/ratatui/blob/images/examples/line_gauge.gif?raw=true
[minimal.gif]: https://github.com/ratatui/ratatui/blob/images/examples/minimal.gif?raw=true
[modifiers.gif]: https://github.com/ratatui/ratatui/blob/images/examples/modifiers.gif?raw=true
[panic.gif]: https://github.com/ratatui/ratatui/blob/images/examples/panic.gif?raw=true
[paragraph.gif]: https://github.com/ratatui/ratatui/blob/images/examples/paragraph.gif?raw=true
[popup.gif]: https://github.com/ratatui/ratatui/blob/images/examples/popup.gif?raw=true
[ratatui-logo.gif]: https://github.com/ratatui/ratatui/blob/images/examples/ratatui-logo.gif?raw=true
[scrollbar.gif]: https://github.com/ratatui/ratatui/blob/images/examples/scrollbar.gif?raw=true
[sparkline.gif]: https://github.com/ratatui/ratatui/blob/images/examples/sparkline.gif?raw=true
[table.gif]: https://vhs.charm.sh/vhs-6njXBytDf0rwPufUtmSSpI.gif
[tabs.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tabs.gif?raw=true
[tracing.gif]: https://github.com/ratatui/ratatui/blob/images/examples/tracing.gif?raw=true
[user_input.gif]: https://github.com/ratatui/ratatui/blob/images/examples/user_input.gif?raw=true
[alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
[BREAKING-CHANGES.md]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/barchart.tape`
Output "target/barchart-grouped.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1000
Hide
Type "cargo run --example=barchart-grouped"
Enter
Sleep 1s
Show
Sleep 1s

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/barchart.tape`
Output "target/barchart.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Hide
Type "cargo run --example=barchart"
Enter
Sleep 1s
Show
Sleep 1s

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/block.tape`
Output "target/block.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1200
Hide
Type "cargo run --example=block"
Enter
Sleep 2s
Show
Sleep 2s

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/calendar.tape`
Output "target/calendar.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 800
Hide
Type "cargo run --example=calendar --features=crossterm,widget-calendar"
Enter
Sleep 3s
Show
Sleep 5s

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/colors.tape`
Output "target/colors.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1410
Hide
Type "cargo run --example=colors --features=crossterm"
Enter
Sleep 2s
Show
Sleep 1s

View File

@@ -1,39 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/docsrs.tape`
# NOTE: Requires VHS 0.6.1 or later for Screenshot support
Output "target/docsrs.gif"
Set Theme "Aardvark Blue"
# The reason for this strange size is that the social preview image for this
# demo is 1280x64 with 80 pixels of padding on each side. We want a version
# without the padding for README.md, etc.
Set Width 640
Set Height 160
Set Padding 0
Hide
Type "cargo run --example docsrs --features crossterm"
Enter
Sleep 2s
Show
Sleep 1s
Screenshot "target/docsrs-hello.png"
Sleep 1s
Hide
Type "q"
Type "cargo run --example docsrs --features crossterm -- layout"
Enter
Sleep 2s
Show
Sleep 1s
Screenshot "target/docsrs-layout.png"
Sleep 1s
Hide
Type "q"
Type "cargo run --example docsrs --features crossterm -- styling"
Enter
Sleep 2s
Show
Sleep 1s
Screenshot "target/docsrs-styling.png"
Sleep 1s
Hide
Type "q"

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/line_gauge.tape`
Output "target/line_gauge.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 400
Hide
Type "cargo run -p ratatui-widgets --example line_gauge"
Enter
Sleep 1s
Show
Sleep 6s

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/paragraph.tape`
Output "target/paragraph.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 1800
Hide
Type "cargo run --example=paragraph --features=crossterm"
Enter
Sleep 1s
Show
Sleep 5s

View File

@@ -1,14 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/ratatui-logo.tape`
Output "target/ratatui-logo.gif"
Set Theme "Aardvark Blue"
Set Width 550
Set Height 220
Hide
Type "cargo run --example=ratatui-logo --features=crossterm"
Enter
Sleep 2s
Show
Sleep 2s
Hide
Escape

View File

@@ -1,12 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/sparkline.tape`
Output "target/sparkline.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 600
Hide
Type "cargo run --example=sparkline --features=crossterm"
Enter
Sleep 1s
Show
Sleep 5s

View File

@@ -1,15 +0,0 @@
# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
# To run this script, install vhs and run `vhs ./examples/tabs.tape`
Output "target/tabs.gif"
Set Theme "Aardvark Blue"
Set Width 1200
Set Height 368
Hide
Type "cargo run --example=tabs --features=crossterm"
Enter
Sleep 2s
Show
Sleep 1s
Right@2.5s 3
Left@2.5s 3
Sleep 2s