ExRatatui

Elixir bindings for the Rust ratatui terminal UI library, via Rustler NIFs.

Build rich terminal UIs in Elixir with ratatui's layout engine, widget library, and styling system together with the BEAM superpowers.

Features

• 24 built-in widgets — Paragraph, Block, List, Table, Gauge, BarChart, Chart, Canvas, Calendar, Tabs, TextInput, Textarea, Markdown, Image, BigText, CodeBlock, and more
• Constraint-based layout — percentages, lengths, ratios, min/max, and fill constraints, with flex alignment and spacing
• Rich styling — named, RGB, and 256-indexed colors, text modifiers, per-span rich text, and a semantic theme palette
• Two runtimes — LiveView-style callbacks or an Elm-style reducer with commands and subscriptions, both OTP-supervised
• Transport-agnostic apps — the same module serves a local terminal, SSH clients, or remote BEAM nodes over Erlang distribution
• Non-terminal rendering — expose the rendered cell buffer to Phoenix LiveView, embedded framebuffers, and screenshot tools
• Images in the terminal — PNG / JPEG / GIF / WebP rendered via Kitty, Sixel, iTerm2, or halfblocks, adapting to the terminal at hand
• Syntax-highlighted code and big text — CodeBlock with curated themes; oversized 8×8 pixel text for titles and banners
• Full event handling — non-blocking keyboard, mouse, resize, focus, and bracketed-paste events
• Focus management — a declarative focus ring with Tab cycling and mouse hit-testing for multi-panel apps
• Custom widgets in pure Elixir — compose primitives into reusable widgets via a protocol, no Rust required
• First-class testing — headless backend and event injection for CI-friendly assertions
• Observability built in — :telemetry events across runtime, render, and transports
• Precompiled NIFs — no Rust toolchain needed; event polling runs on the DirtyIo scheduler and never blocks the BEAM

Installation

Add ex_ratatui to the dependencies in mix.exs:

def deps do
  [
    {:ex_ratatui, "~> 0.10"}
  ]
end

Then fetch and compile:

mix deps.get && mix compile

A precompiled NIF binary for the host platform is downloaded automatically. The native library itself is loaded lazily on first use, so compiling a project that depends on ex_ratatui does not require the NIF to be loaded into the compiler VM.

Prerequisites

• Elixir 1.17+

Precompiled NIF binaries are available for Linux (x86_64, aarch64, armv6/hf, riscv64), macOS (x86_64, aarch64), and Windows (x86_64). No Rust toolchain needed.

To compile from source instead, install the Rust toolchain and set:

export EX_RATATUI_BUILD=true

Quick Start

alias ExRatatui.Layout.Rect
alias ExRatatui.Style
alias ExRatatui.Widgets.{Block, Paragraph}

ExRatatui.run(fn terminal ->
  {w, h} = ExRatatui.terminal_size()

  paragraph = %Paragraph{
    text: "Hello from ExRatatui!\n\nPress any key to exit.",
    style: %Style{fg: :green, modifiers: [:bold]},
    alignment: :center,
    block: %Block{
      title: " Hello World ",
      borders: [:all],
      border_type: :rounded,
      border_style: %Style{fg: :cyan}
    }
  }

  ExRatatui.draw(terminal, [{paragraph, %Rect{x: 0, y: 0, width: w, height: h}}])

  # Wait for a keypress, then exit
  ExRatatui.poll_event(60_000)
end)

Try the examples catalog for more — every widget has a focused, copyable demo, e.g. mix run examples/basics/hello_world.exs.

New here? The Getting Started guide builds a supervised todo app from mix new to a working TUI.

Runtimes and Transports

ExRatatui offers two ways to structure a supervised app and several ways to serve it — every combination works, and switching transport doesn't change the app module.

• Runtimes: the Callback Runtime (LiveView-style mount/render/handle_event, the default) and the Reducer Runtime (Elm-style single update/2 with first-class commands and subscriptions). The callback guide has a side-by-side comparison.
• Transports: local terminal (the default), SSH, Erlang distribution, custom transports, and non-terminal surfaces. The Transports guide has the canonical feature matrix.

Guides

Guide	Description
Getting Started	Walk-through from mix new to a supervised TUI — the place to start
Building UIs	Widgets, layout, styles, rich text, and events — everything for render/2
Custom Widgets	Compose primitives into reusable widgets via the ExRatatui.Widget protocol
Images	Image rendering across terminals and transports — protocols, resizing, telemetry
Paste and Clipboard	Bracketed paste behaviour, batch-insert helpers, and an OSC 52 copy snippet
Callback Runtime	OTP-supervised apps with mount, render, handle_event, and handle_info callbacks
Reducer Runtime	Elm-style apps with init, update, subscriptions, commands, and runtime inspection
State Machine Patterns	Multi-screen apps, modals, and conditional UI without the tangle
Transports	Canonical feature matrix — what works where across Local / Session / SSH / Distributed / CellSession
Running TUIs over SSH	Serve any app as a remote TUI over SSH, standalone or under nerves_ssh
Running TUIs over Erlang Distribution	Drive a TUI from a remote BEAM node with zero NIF on the app side
Custom Transports	Plug in a custom transport (TCP, Livebook, WebSocket) via the ExRatatui.Transport behaviour
Rendering to Non-Terminal Surfaces	Use ExRatatui.CellSession to expose the rendered cell buffer to LiveView, framebuffers, screenshot tools, and other non-ANSI consumers
Architecture	The NIF bridge and the per-transport process trees
Testing	Headless backend, test_mode, inject_event, and assertion patterns
Debugging	Runtime.snapshot, tracing, buffer inspection, and common errors
Performance	Render-loop tuning, render?: false, large trees, async effects
Telemetry	:telemetry events for runtime, render, transport, and session — logging, metrics, OpenTelemetry
Widgets Cheatsheet	One-page reference with every struct and its key fields

How It Works

ExRatatui bridges Elixir and Rust through Rustler NIFs: widget structs are encoded across the NIF boundary and decoded into ratatui types for rendering, while terminal events are polled on BEAM's DirtyIo scheduler so nothing blocks Elixir processes. Every transport builds on the same supervised Server process, with full session isolation per connected client.

The Architecture guide has the full picture — the NIF bridge and the per-transport process trees.

Ecosystem

• kino_ex_ratatui — Run TUIs inside Livebook notebooks.
• phoenix_ex_ratatui — Run TUIs in the browser within Phoenix LiveView.

Built with ExRatatui

• ash_tui — Interactive terminal explorer for Ash domains, resources, attributes, actions, and more.
• bb_tui — Terminal-based dashboard for Beam Bots robots.
• switchyard — Full-featured reducer runtime workbench exercising command batching, async effects, subscription reconciliation, runtime snapshots, distributed attach, and row-scrolled WidgetList.
• nerves_ex_ratatui_example — Example Nerves project with two TUIs (system monitor and LED control) on embedded hardware, reachable over SSH subsystems and Erlang distribution.
• phoenix_ex_ratatui_example — Example Phoenix project with a TUI served over SSH and Erlang distribution alongside a public LiveView chat room, sharing PubSub between the browser and the terminal.
• ... yours? Open a PR! Plenty of ideas to explore in awesome-ratatui.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and PR guidelines.

License

MIT — see LICENSE for details.