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
• Single-binary distribution — ship a TUI as one native executable per OS/arch via Burrito, no Erlang or Rust install needed on the target machine; mix ex_ratatui.gen.burrito scaffolds the wiring

Installation

Add ex_ratatui to the dependencies in mix.exs:

def deps do
  [
    {:ex_ratatui, "~> 0.16"}
  ]
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

Precompiled NIF binaries are available for Linux (x86_64, aarch64, armv6/hf, riscv64), macOS (x86_64, aarch64), and Windows (x86_64), covering NIF ABI versions 2.16 (OTP 26) and 2.17 (OTP 27/28) — no Rust toolchain needed. OTP 29 raised the ABI to 2.18; since the NIF ABI is backward compatible, OTP 29 loads the 2.17 binary and also needs no Rust toolchain. A native 2.18 build is pending rustler_precompiled support upstream.

The Linux glibc binaries are built against old C libraries on purpose, and the release refuses to publish one that needs more: glibc 2.28 for aarch64, armv6/hf, and riscv64 (so they load on Nerves systems and older distributions), and glibc 2.35 for x86_64. The musl binaries are self-contained.

On musl systems (Alpine, single-binary Burrito payloads, Nerves-style rootfs): the *-unknown-linux-musl artifacts published up to v0.11.2 dynamically link libgcc_s.so.1, which stock musl systems do not ship — apk add libgcc fixes the resulting relocation error. Artifacts from later releases embed the unwinder statically and depend on musl libc alone.

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

export EX_RATATUI_BUILD=true

Or, without an env var, in your config/config.exs:

config :rustler_precompiled, :force_build, ex_ratatui: true

The application config takes precedence over EX_RATATUI_BUILD, and config :rustler_precompiled, force_build_all: true takes precedence over both.

Either way, forcing a build also requires Rustler in the consuming project's dependencies — ex_ratatui declares :rustler as optional, and optional dependencies are not fetched transitively, so without it the build fails with Rustler.Compiler is not available:

{:rustler, ">= 0.0.0"}

Forcing a build is also required when depending on a git tag instead of Hex ({:ex_ratatui, github: "mcass19/ex_ratatui", tag: "..."}): the checksum file for a release's precompiled artifacts can only be committed after the tag triggers their build, so each tag predates its own checksums and the precompiled path fails with the precompiled NIF file does not exist in the checksum file. The Hex package always carries the complete checksum file.

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, including pixel displays through raster_ex_ratatui. The Transports guide has the canonical feature matrix.

Guides

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.
• raster_ex_ratatui — Run TUIs on pixel displays such as e-ink panels, with helpers for Linux framebuffers.

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.
• caudata — Zero-config multi-server log streamer aggregating real-time logs from remote Linux hosts over native SSH, with Docker/Systemd/Launchd discovery and live CPU, RAM, and disk metrics.
• ex_athena — Provider-agnostic AI agent loop with a terminal chat TUI (via mix athena.chat), supporting Ollama, OpenAI-compatible, llama.cpp, and Anthropic backends.
• beamcore — Terminal coding agent where each instance is a distributed OTP node, with in-VM code execution, persistent memory, mesh RPC, live runtime attachment, and multi-provider LLM support.
• extop — Live Linux system monitor with real-time CPU, GPU, memory, disk, and network charts alongside a sortable, filterable process table with signal management.
• phoenix_gen_api_tui — Terminal-based explorer for PhoenixGenApi applications, with runtime inspection of services, call flows, cluster topology, health, and rate limits — no database connection required.
• 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.

Acknowledgements

ExRatatui is undeniably inspired by ratatui. Having such a great terminal UI library in Rust was the motivation to bring the same experience to the Elixir world and combine the best of both worlds. Special thanks to the great community behind ratatui.

The ExRatatui logo adapts the ratatui logo designed by Pavel Fomchenkov, with the Elixir drop and ex_ratatui wordmark added by Malena Merlina.

License

MIT — see LICENSE for details.