ratatui_ruby

Introduction

ratatui_ruby is a Ruby wrapper for Ratatui. It allows you to cook up Terminal User Interfaces in Ruby. ratatui_ruby is a community wrapper that is not affiliated with the Ratatui team.

{Why RatatuiRuby?}[./doc/getting_started/why.md] — Native Rust performance, zero runtime overhead, and Ruby’s expressiveness. See how we compare to CharmRuby, raw Rust, and Go.

Please join the announce mailing list at lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the trunk branch for pre-release updates.

Quick Links

The Ecosystem

RatatuiRuby: Core engine • Tea: MVU architecture • Kit: Component architecture (Planned) • DSL: Glimmer syntax (Planned) • Framework: Omakase framework (Planned) • UI: Polished widgets (Planned) • UI Pro: More polished widgets (Planned)

For App Developers

Get Started: Quickstart • Examples ⸺ Stay Informed: Announce List • FAQ ⸺ Reach Out: Discuss List • Bug Tracker

For Contributors

Get Started: Contributing Guide • Code of Conduct ⸺ Stay Informed: Announce List • Project History ⸺ Reach Out: Development List • Bug Tracker

Compatibility

ratatui_ruby is designed to run on everything Ruby does, including:

• GNU/Linux, macOS, Windows, OpenBSD, and FreeBSD; and

• x86_64 (AMD, Intel) and ARM (Apple Silicon, Raspberry Pi).

We support the latest minor version of every non-eol Ruby version, including Ruby 4.

Installation

Add this line to your application’s Gemfile:

gem "ratatui_ruby"

And then execute:

bundle install

Or install it yourself with:

gem install ratatui_ruby

Usage

ratatui_ruby uses an immediate-mode API. You describe your UI using Ruby objects and call draw in a loop.

RatatuiRuby.run do |tui|
  loop do
    tui.draw do |frame|
      frame.render_widget(
        tui.paragraph(
          text: "Hello, Ratatui! Press 'q' to quit.",
          alignment: :center,
          block: tui.block(
            title: "My Ruby TUI App",
            borders: [:all],
            border_style: { fg: "cyan" }
          )
        ),
        frame.area
      )
    end
    case tui.poll_event
    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
      break
    else
      nil
    end
  end
end

Ratatui

For a full tutorial, see the Quickstart. For an explanation of the application architecture, see Application Architecture.

Features

ratatui_ruby gives you 20+ widgets out of the box:

Plus: flexible layouts with constraints, full keyboard/mouse/paste/resize events, snapshot testing, and hex/RGB/256-color support.

Documentation

Contributing

Bug reports and pull requests are welcome on sourcehut at sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the Code of Conduct.

Issues for the underlying Rust library should be filed at ratatui/ratatui.

Want to help develop ratatui_ruby? Check out the contribution guide on the wiki.

Note: Active development happens on the trunk branch. Use trunk if you are a contributor or want the latest cutting-edge features. stable is for stable releases only.

Copyright & License

ratatui_ruby is copyright 2025, Kerrick Long.

The library is LGPL-3.0-or-later: you can use it in proprietary applications, but you must share changes you make to ratatui_ruby itself. Documentation snippets and widget examples are MIT-0: copy and use them without attribution.

Documentation is CC-BY-SA-4.0. Build tooling and full app examples are AGPL-3.0-or-later. See each file’s SPDX comment for specifics.

Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the REUSE Specification – Version 3.3 for details.

This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. declare-ai.org