README
¶
Examples
Your first app: Purrfect Day, a colorful cat-care
checklist with a happiness meter. Follow the getting-started tutorial
to build it yourself, or run go run ./examples/apps/getting-started.
Each directory is a self-contained program: whole applications under apps, one program per widget under widgets. Run one with:
go run ./examples/apps/<name>
go run ./examples/widgets/<name>
The widget examples draw a single frame and quit on the first key, and so do
the applications that are really one picture; the rest keep running. Each
says what keys it responds to in the table below and in the doc comment at the
top of its main.go.
Nothing is shared between examples on purpose: each carries its own terminal setup and event loop so that it can be read start to finish, and pasted into an application as it stands. That is ratatui's convention for its own examples, and the reason the same twenty lines of scaffolding appear in every one of them.
Applications
Whole programs, including ports from ratatui's examples/apps:
| Example | Shows | Keys |
|---|---|---|
| getting-started | Purrfect Day: beginner-friendly layout, styled checklist, cat companion, and happiness gauge | Up/Down or j/k, Space/Enter toggle, r reset, q/Esc/Ctrl+C quit |
| advanced-widget-impl | The shapes a widget takes: built for one frame, over longer-lived state, a container of other widgets, and one that records where it drew | any key quits |
| async-github | Fetching in the background: a goroutine filling a table in while the UI keeps drawing | j/k, arrows, q |
| calendar-explorer | A year of Monthly calendars with the holidays marked, in each of the widget's styles |
s, n/p, arrows or h/j/k/l, q |
| canvas | Four canvases at once: a world map, a scratchpad, a bouncing ball and a ruler, in every marker | Enter, arrows or h/j/k/l, mouse, q |
| chart | A scrolling pair of sine waves beside a bar, a line and a scatter chart | q |
| color-explorer | Every colour catatui can name or number, as text and as backgrounds | any key quits |
| colors-rgb | Every colour a 24-bit terminal can show, animated, two pixels to a cell | any key quits |
| constraint-explorer | The same constraints under all six Flex modes at once, edited live |
arrows or h/j/k/l, 1-6, a, x, +/-, q |
| constraints | What each kind of Constraint gives way to, a tab per kind |
arrows or h/j/k/l, g/G, q |
| custom-widget | Writing a widget from scratch: a button drawn cell by cell, driven by the mouse | arrows or h/l, Space, mouse, q |
| demo | The original tui-rs demo: three tabs of gauges, lists, charts, a table and a world map, animating on a tick | arrows or h/j/k/l, t, q |
| flex | What each Flex mode does to the same constraints, side by side |
arrows, g/G, -/+, q |
| gauge | Four gauges filling at once: percentage against ratio, whole cells against eighths | Enter, q |
| hello | Layout, direct buffer drawing, and an event loop that blocks when idle | arrows, mouse, q |
| hyperlink | A clickable link, using OSC 8 and CellForcedWidth to keep an escape sequence out of the width calculation |
any key quits |
| inline | An inline viewport, and InsertBefore pushing finished lines into the scrollback |
q |
| input-form | Moving the focus between fields, and putting the cursor where the focused one wants it | Tab, Enter, Esc |
| minimal | The least a catatui program can be: set up, draw, quit | any key quits |
| modifiers | Every modifier against five foreground and background colours, so you can see which your terminal renders | any key quits |
| mouse-drawing | Drawing with the mouse, joining up a drag with Bresenham's line algorithm | mouse, Space, q |
| panic | What a panic does to the terminal with term.RecoverAndRestore deferred, and without it |
p, e, h, q |
| popup | A popup drawn over the rest of the UI, with Clear behind it |
p, q |
| release-header | A fixed viewport, the logo over a gradient, and two blocks merging their borders | any key quits |
| scrollbar | Four Scrollbars over the same text, differing in arrows, track and thumb |
arrows or h/j/k/l, q |
| table | An interactive Table with a scrollbar, row, column and cell selection, and swappable colours |
arrows or h/j/k/l, Shift with either, q |
| todo-list | A list whose items are selected and ticked off, with the selection kept in a ListState |
arrows or h/j/k/l, g/G, Enter, q |
| tracing | Logging to a file with log/slog while the terminal is given over to the UI |
q |
| user-input | Typing into an input box: editing modes, and where the cursor goes | e, Esc, Enter, arrows, q |
| volatility-surface | 3D in a terminal: rotation, perspective and a braille Canvas, drawing a surface you can turn |
arrows or h/j/k/l, z/x, p, space, ctrl-r, q |
| weather | A day of temperatures as a BarChart, coloured yellow through red |
any key quits |
| widget-ref-container | Widgets of different types in one container, which in Go is a slice of the interface | any key quits |
Widgets
One program per widget, ported from ratatui-widgets/examples:
| Example | Shows | Keys |
|---|---|---|
| barchart | BarChart drawn both ways up |
any key quits |
| barchart-grouped | BarChart with grouped bars and value labels |
any key quits |
| block | Block borders, styles and border types |
any key quits |
| calendar | Monthly, with events and header styles |
any key quits |
| canvas | Canvas: a world map, lines, rectangles and points on layers |
any key quits |
| chart | Chart: a line plot and a filled area plot on shared axes |
any key quits |
| collapsed-borders | Block.MergeBorders and Overlap spacing, so neighbours share one border |
arrows, q |
| gauge | Gauge and LineGauge |
any key quits |
| line-gauge | LineGauge filling up on a timer |
space, r, q |
| list | List with a moving selection, and a bottom-to-top list |
j/k, arrows, q |
| logo | CatatuiLogo in an inline viewport, leaving the scrollback alone |
any key quits |
| paragraph | Paragraph alignment, wrapping and styled spans |
any key quits |
| scrollbar | Scrollbar on both axes, scrolling a paragraph |
h/j/k/l, arrows, q |
| shadow | Shadow: overlay, block, symbol and dimmed, behind a popup |
any key quits |
| sparkline | Sparkline, including an animated sine wave |
any key quits |
| table | Table with row, column and cell selection |
h/j/k/l, g/G, q |
| tabs | Tabs drawn over the top border of a block |
h/l, arrows, q |
Except for hello, every example is a port of the file or crate of the same
name in ratatui at ratatui-v0.30.2, and names its source in a header comment.
The split follows ratatui, where the two sets live in different crates: several
names, table and gauge among them, belong to one of each.
Each one also has a render_test.go that draws it at sizes from 0x0 up to
200x60. Drawing outside the area a widget is given panics in catatui, so those
tests are what keep the examples working as the library changes. Nothing in
them reaches the network: async-github takes the URL it fetches, and its tests
point it at a server in the same process.
Three examples need something ratatui takes from a crate, and catatui will not
add a dependency for one example. colors-rgb carries the Okhsv conversion the
palette crate does, in okhsv.go; volatility-surface carries the colormaps
the colorgrad crate holds, generated into colormaps.go by
tools/gen_colormaps.py; async-github uses net/http and encoding/json
where ratatui uses octocrab and tokio.
Directories
¶
| Path | Synopsis |
|---|---|
|
apps
|
|
|
advanced-widget-impl
command
Command advanced-widget-impl shows the ways a type can be a widget, and what each one is for.
|
Command advanced-widget-impl shows the ways a type can be a widget, and what each one is for. |
|
async-github
command
Command async-github fetches ratatui's open pull requests in the background and shows them in a table while the UI keeps running.
|
Command async-github fetches ratatui's open pull requests in the background and shows them in a table while the UI keeps running. |
|
calendar-explorer
command
Command calendar-explorer draws a whole year of Monthly calendars, with the holidays and the solstices marked, in each of the styles the widget offers.
|
Command calendar-explorer draws a whole year of Monthly calendars, with the holidays and the solstices marked, in each of the styles the widget offers. |
|
canvas
command
Command canvas draws four canvases at once: a world map, a scratchpad, a bouncing ball and a row of rectangles.
|
Command canvas draws four canvases at once: a world map, a scratchpad, a bouncing ball and a row of rectangles. |
|
chart
command
Command chart draws four charts at once: a scrolling pair of sine waves, a bell curve as bars, a line through two points, and a scatter plot.
|
Command chart draws four charts at once: a scrolling pair of sine waves, a bell curve as bars, a line through two points, and a scatter plot. |
|
color-explorer
command
Command color-explorer draws every colour catatui can name or number, so you can see what your terminal actually makes of them.
|
Command color-explorer draws every colour catatui can name or number, so you can see what your terminal actually makes of them. |
|
colors-rgb
command
Command colors-rgb fills the terminal with every colour it can show, and animates them.
|
Command colors-rgb fills the terminal with every colour it can show, and animates them. |
|
constraint-explorer
command
Command constraint-explorer lets you build a set of constraints and watch every Flex mode lay them out at once.
|
Command constraint-explorer lets you build a set of constraints and watch every Flex mode lay them out at once. |
|
constraints
command
Command constraints shows what each kind of Constraint does, a tab per kind.
|
Command constraints shows what each kind of Constraint does, a tab per kind. |
|
custom-widget
command
Command custom-widget is a button drawn from scratch, and three of them wired to the mouse.
|
Command custom-widget is a button drawn from scratch, and three of them wired to the mouse. |
|
demo
command
Command demo is the original tui-rs demo, the one the ratatui README shows: three tabs of gauges, lists, charts, a table and a world map, all animating on a tick.
|
Command demo is the original tui-rs demo, the one the ratatui README shows: three tabs of gauges, lists, charts, a table and a world map, all animating on a tick. |
|
flex
command
Command flex shows what each Flex mode does to the same set of constraints.
|
Command flex shows what each Flex mode does to the same set of constraints. |
|
gauge
command
Command gauge fills four gauges at once, which is what shows the difference between the ways of measuring them.
|
Command gauge fills four gauges at once, which is what shows the difference between the ways of measuring them. |
|
getting-started
command
Command getting-started is Purrfect Day, the app built in docs/getting-started.md.
|
Command getting-started is Purrfect Day, the app built in docs/getting-started.md. |
|
hello
command
Command hello is a minimal catatui application: a constraint-driven layout, direct buffer drawing, and an event loop that blocks when idle.
|
Command hello is a minimal catatui application: a constraint-driven layout, direct buffer drawing, and an event loop that blocks when idle. |
|
hyperlink
command
Command hyperlink draws a line of text that is a clickable link, using the OSC 8 escape sequence.
|
Command hyperlink draws a line of text that is a clickable link, using the OSC 8 escape sequence. |
|
inline
command
Command inline shows the inline viewport: a fixed block of the terminal that redraws in place while finished lines scroll away above it.
|
Command inline shows the inline viewport: a fixed block of the terminal that redraws in place while finished lines scroll away above it. |
|
input-form
command
Command input-form is a form with three fields and a focus that moves between them.
|
Command input-form is a form with three fields and a focus that moves between them. |
|
minimal
command
Command minimal is the smallest catatui program that draws something: set up the terminal, draw one frame, quit on the first key.
|
Command minimal is the smallest catatui program that draws something: set up the terminal, draw one frame, quit on the first key. |
|
modifiers
command
Command modifiers draws every modifier against every pairing of five foreground and background colours, so you can see which of them your terminal actually renders.
|
Command modifiers draws every modifier against every pairing of five foreground and background colours, so you can see which of them your terminal actually renders. |
|
mouse-drawing
command
Command mouse-drawing is a scratchpad you draw on with the mouse.
|
Command mouse-drawing is a scratchpad you draw on with the mouse. |
|
panic
command
Command panic shows what a panic does to the terminal, with catatui's recovery in place and without it.
|
Command panic shows what a panic does to the terminal, with catatui's recovery in place and without it. |
|
popup
command
Command popup shows how to draw a popup over the top of the rest of the UI.
|
Command popup shows how to draw a popup over the top of the rest of the UI. |
|
release-header
command
Command release-header draws the banner that goes with a catatui release: the logo over a rainbow shadow, the version, and a menu of the packages.
|
Command release-header draws the banner that goes with a catatui release: the logo over a rainbow shadow, the version, and a menu of the packages. |
|
scrollbar
command
Command scrollbar draws four scrollbars over the same text, each built a different way.
|
Command scrollbar draws four scrollbars over the same text, each built a different way. |
|
table
command
Command table is a table of people with a scrollbar, a moving selection and a colour scheme that can be changed while it runs.
|
Command table is a table of people with a scrollbar, a moving selection and a colour scheme that can be changed while it runs. |
|
todo-list
command
Command todo-list is a todo list whose items can be selected and ticked off.
|
Command todo-list is a todo list whose items can be selected and ticked off. |
|
tracing
command
Command tracing logs to a file while the terminal is given over to the UI, and shows the last few events it handled.
|
Command tracing logs to a file while the terminal is given over to the UI, and shows the last few events it handled. |
|
user-input
command
Command user-input shows how to handle keyboard input: an input box that records what is typed, and a list of the messages entered so far.
|
Command user-input shows how to handle keyboard input: an input box that records what is typed, and a list of the messages entered so far. |
|
volatility-surface
command
Command volatility-surface draws a 3D wireframe in the terminal: an implied volatility surface you can turn, tilt and zoom while it moves.
|
Command volatility-surface draws a 3D wireframe in the terminal: an implied volatility surface you can turn, tilt and zoom while it moves. |
|
weather
command
Command weather draws a day of made-up temperatures as a vertical bar chart, one bar per hour, coloured from yellow through to red.
|
Command weather draws a day of made-up temperatures as a vertical bar chart, one bar per hour, coloured from yellow through to red. |
|
widget-ref-container
command
Command widget-ref-container keeps widgets of different types in one container and renders them down the screen.
|
Command widget-ref-container keeps widgets of different types in one container and renders them down the screen. |
|
widgets
|
|
|
barchart
command
Command barchart shows catatui's BarChart widget in both directions.
|
Command barchart shows catatui's BarChart widget in both directions. |
|
barchart-grouped
command
Command barchart-grouped shows catatui's BarChart widget with grouped bars.
|
Command barchart-grouped shows catatui's BarChart widget with grouped bars. |
|
block
command
Command block shows catatui's Block widget: borders, styles and border types.
|
Command block shows catatui's Block widget: borders, styles and border types. |
|
calendar
command
Command calendar shows catatui's Monthly widget with two styled months.
|
Command calendar shows catatui's Monthly widget with two styled months. |
|
canvas
command
Command canvas shows catatui's Canvas widget: a world map with shapes and points drawn over it.
|
Command canvas shows catatui's Canvas widget: a world map with shapes and points drawn over it. |
|
chart
command
Command chart shows catatui's Chart widget: a line plot and a filled area plot sharing a pair of axes.
|
Command chart shows catatui's Chart widget: a line plot and a filled area plot sharing a pair of axes. |
|
collapsed-borders
command
Command collapsed-borders shows four blocks sharing their borders, with the selected one drawn on top in a thick border.
|
Command collapsed-borders shows four blocks sharing their borders, with the selected one drawn on top in a thick border. |
|
gauge
command
Command gauge shows catatui's Gauge and LineGauge widgets.
|
Command gauge shows catatui's Gauge and LineGauge widgets. |
|
line-gauge
command
Command line-gauge shows catatui's LineGauge widget filling up over time.
|
Command line-gauge shows catatui's LineGauge widget filling up over time. |
|
list
command
Command list shows catatui's List widget, including a bottom-to-top list.
|
Command list shows catatui's List widget, including a bottom-to-top list. |
|
logo
command
Command logo draws the catatui logo in an inline viewport: three rows at the shell's cursor, leaving the scrollback above them untouched.
|
Command logo draws the catatui logo in an inline viewport: three rows at the shell's cursor, leaving the scrollback above them untouched. |
|
paragraph
command
Command paragraph shows catatui's Paragraph widget: alignment and wrapping.
|
Command paragraph shows catatui's Paragraph widget: alignment and wrapping. |
|
scrollbar
command
Command scrollbar shows catatui's Scrollbar widget, vertical and horizontal, scrolling a paragraph.
|
Command scrollbar shows catatui's Scrollbar widget, vertical and horizontal, scrolling a paragraph. |
|
shadow
command
Command shadow shows catatui's Shadow widget: four ways to cast a shadow behind a popup.
|
Command shadow shows catatui's Shadow widget: four ways to cast a shadow behind a popup. |
|
sparkline
command
Command sparkline shows catatui's Sparkline widget, including an animated sine wave.
|
Command sparkline shows catatui's Sparkline widget, including an animated sine wave. |
|
table
command
Command table shows catatui's Table widget with row, column and cell selection.
|
Command table shows catatui's Table widget with row, column and cell selection. |
|
tabs
command
Command tabs shows catatui's Tabs widget over a block of content.
|
Command tabs shows catatui's Tabs widget over a block of content. |
Click to show internal directories.
Click to hide internal directories.