RatatuiRuby TUI development for terminal user interfaces

version
1.2.2
GitHub stars
38

Install

/plugin install ratatui-ruby@claude-ruby-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add hoblin/claude-ruby-marketplace.

Contents

Discovered from source

Skills 1

RatatuiRuby

This skill provides guidance for building terminal user interfaces with RatatuiRuby, a Ruby gem wrapping Rust's Ratatui library. Use for TUI development, terminal widgets, layout systems, event handling, and testing terminal applications.

Quick Reference

Minimal Application

require "ratatui_ruby"

RatatuiRuby.run do |tui|
  loop do
    tui.draw do |frame|
      widget = tui.paragraph(text: "Hello, TUI!", block: tui.block(title: "App"))
      frame.render_widget(widget, frame.area)
    end

    case tui.poll_event
    in {type: :key, code: "q"}
      break
    in {type: :key, code: "c", modifiers: ["ctrl"]}
      break
    else
      # Continue
    end
  end
end

Key Concepts

ConceptPurpose
RatatuiRuby.runManaged loop handling terminal setup/teardown
tui.drawRender widgets each frame
tui.poll_eventCapture keyboard/mouse input
frame.areaAvailable rendering area (Rect)
frame.render_widgetRender stateless widgets
frame.render_stateful_widgetRender widgets with state (List, Table)

Two Operating Modes

ModeUse CaseSetup
Full-ScreenComplete TUI applicationsRatatuiRuby.run { } (default)
Inline ViewportRich CLI moments (spinners, progress)RatatuiRuby.run(viewport: :inline, height: 5) { }

Full-Screen: Takes over terminal, alternate screen, restored on exit.

Inline Viewport: Preserves scrollback, fixed-height widget area, output remains visible after exit.

Core Pattern

The managed loop pattern handles terminal lifecycle:

RatatuiRuby.run do |tui|
  loop do
    # 1. Draw UI
    tui.draw do |frame|
      # Render widgets
    end

    # 2. Handle events
    case tui.poll_event
    in {type: :key, code: "q"}
      break
    end
  end
end

Common Widgets

WidgetFactoryPurpose
Paragraphtui.paragraph(text:)Text display
Blocktui.block(title:, borders:)Borders, titles, padding
Listtui.list(items:)Selectable item list
Tabletui.table(rows:, widths:)Tabular data
Gaugetui.gauge(ratio:)Progress indication
Tabstui.tabs(titles:)Tab navigation
Charttui.chart(datasets:)Data visualization
Canvastui.canvas { }Custom drawing
Scrollbartui.scrollbarScroll indication

Stateless vs Stateful Widgets

Stateless (Paragraph, Block, Gauge):

widget = tui.paragraph(text: "Hello")
frame.render_widget(widget, frame.area)

Stateful (List, Table):

# Create state once (outside draw loop)
list_state = tui.list_state(0)

# In draw block
list = tui.list(items: ["Item A", "Item B", "Item C"])
frame.render_stateful_widget(list, frame.area, list_state)

# Update state on input
list_state.select_next if event_down?

Block Composition

Wrap widgets with Block for borders and titles:

block = tui.block(
  title: "Main",
  titles: [
    {content: "Help: q", position: :bottom, alignment: :right}
  ],
  borders: [:all],
  border_style: {fg: "cyan"}
)

paragraph = tui.paragraph(text: "Content", block:)

Layout

Split areas using constraints:

layout = tui.layout(
  direction: :vertical,
  constraints: [
    tui.constraint(:percentage, 20),  # Header: 20%
    tui.constraint(:min, 0),           # Body: remaining
    tui.constraint(:length, 3)         # Footer: 3 rows
  ]
)

chunks = layout.split(frame.area)
# chunks[0] -> header area
# chunks[1] -> body area
# chunks[2] -> footer area

Constraint Types

TypeSyntaxBehavior
Lengthtui.constraint(:length, 5)Fixed 5 rows/cols
Percentagetui.constraint(:percentage, 50)50% of parent
Mintui.constraint(:min, 10)At least 10
Maxtui.constraint(:max, 20)At most 20
Ratiotui.constraint(:ratio, 1, 3)1/3 of space
Filltui.constraint(:fill)Expand into excess

Event Handling

Pattern Matching

case tui.poll_event
in {type: :key, code: "q"}
  break
in {type: :key, code: "j"} | {type: :key, code: "down"}
  list_state.select_next
in {type: :key, code: "k"} | {type: :key, code: "up"}
  list_state.select_previous
in {type: :key, code: "c", modifiers: ["ctrl"]}
  break
in {type: :mouse, kind: "down", button: "left", x:, y:}
  handle_click(x, y)
in {type: :resize}
  # Terminal resized, next draw adapts
end

Event Helper Methods

event = tui.poll_event
break if event.ctrl_c?
list_state.select_next if event.down? || event.j?

Styling

Hash-based syntax for colors and modifiers:

tui.paragraph(
  text: "Styled text",
  style: {fg: "green", bold: true},
  block: tui.block(border_style: {fg: "cyan"})
)

Text Composition

line = tui.line([
  tui.span("Normal "),
  tui.span("Bold", style: {bold: true}),
  tui.span(" Red", style: {fg: "red"})
])

tui.paragraph(text: line)

Color Options

  • Named: "red", "green", "cyan", "white"
  • Hex: "#FF5733"
  • Indexed: 0-255 palette

Testing

require "ratatui_ruby/test_helper"

class MyAppTest < Minitest::Test
  include RatatuiRuby::TestHelper

  def test_renders_greeting
    with_test_terminal(80, 24) do
      RatatuiRuby.draw do |frame|
        widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
        frame.render_widget(widget, frame.area)
      end

      assert_snapshots("greeting")  # Creates/compares snapshots/greeting.txt
    end
  end

  def test_keyboard_navigation
    with_test_terminal do
      inject_keys("j", "j", "k")  # Down, down, up
      # Assert state changes
    end
  end
end

Frameworks

Tea (MVU Architecture)

Functional, Elm-style architecture for predictable state:

require "ratatui_ruby/tea"

class Counter
  include RatatuiRuby::Tea::App

  def init
    [Model.new(count: 0), nil]
  end

  def view(model, tui)
    tui.paragraph(text: "Count: #{model.count}")
  end

  def update(message, model)
    case message
    in {type: :key, code: "q"}
      [model, RatatuiRuby::Tea::Command.exit]
    in {type: :key, code: "j"}
      [model.with(count: model.count + 1), nil]
    else
      [model, nil]
    end
  end
end

Counter.new.run

Best Practices

Do

  • Use RatatuiRuby.run for managed terminal lifecycle
  • Create state objects outside the draw loop
  • Use pattern matching for event handling
  • Use inline viewports for CLI "rich moments"
  • Test with RatatuiRuby::TestHelper

Don't

  • Handle Ctrl+C manually (use event.ctrl_c? helper)
  • Forget to break the loop (leads to CPU spin)
  • Render widgets before poll_event (blocks input)
  • Use full-screen for simple progress indicators

Additional Resources

Reference Files

For detailed API documentation and patterns:

  • references/core-concepts.md - Managed loop, terminal lifecycle, inline vs full-screen
  • references/widgets.md - Complete widget catalog, composition patterns
  • references/layout.md - Constraints, directions, nested layouts
  • references/events.md - Keyboard, mouse, event handling patterns
  • references/styling.md - Colors, modifiers, text composition
  • references/testing.md - TestHelper, snapshots, event injection
  • references/frameworks.md - Tea MVU, Kit components

Sponsors

Details

Marketplace
hoblin/claude-ruby-marketplace
Source
plugins/ratatui-ruby
Category
Tui Development

More from hoblin/claude-ruby-marketplace

All 8