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

• 25 built-in widgets — Paragraph, Block, List, Table, Gauge, BarChart, Chart, Canvas, Calendar, Tabs, TextInput, Textarea, Markdown, Image, BigText, CodeBlock, Viewport3D, 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
• 3D rendering — software-rasterized or ray-traced scenes (Viewport3D) with meshes, lights, materials, a movable camera, and a scene-graph for articulated models, blitted into true-color cells
• 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.11"}
  ]
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+
• Erlang/OTP 26 – 29

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

export EXRATATUIBUILD=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.pollevent(60000) 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/handleevent, 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 | | 3D Rendering | Lit 3D scenes with Viewport3D — meshes, camera, render modes, and pipelines | | Paste and Clipboard | Bracketed paste behaviour, batch-insert helpers, and an OSC 52 copy snippet | | Callback Runtime | OTP-supervised apps with mount, render, handleevent, 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 nervesssh | | 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, testmode, injectevent, 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

• kinoexratatui — Run TUIs inside Livebook notebooks.
• phoenixexratatui — Run TUIs in the browser within Phoenix LiveView.