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 — from paragraphs, lists, and tables to charts, canvas, text inputs, markdown, syntax-highlighted code, images (Kitty, Sixel, iTerm2, halfblocks), and 3D viewports
• Layout and styling — ratatui's constraint-based layout, named, RGB, and indexed colors, and per-span rich text
• Two OTP runtimes — LiveView-style callbacks or an Elm-style reducer with commands and subscriptions, with apps written in Elixir, Erlang, or Gleam
• Serve it anywhere — the same app module runs in a local terminal, over SSH, over Erlang distribution, or on non-terminal surfaces like LiveView and pixel displays
• Full input — keyboard, mouse, resize, focus, and paste events, plus a focus ring for multi-panel apps
• Custom widgets in pure Elixir — compose primitives through a protocol, no Rust required
• Testable and observable — a headless test terminal, event injection, and :telemetry events throughout
• No Rust toolchain needed — precompiled NIFs, with event polling on DirtyIo schedulers so the BEAM never blocks
• Single-binary distribution — ship one native executable per OS/arch via Burrito, scaffolded by mix ex_ratatui.gen.burrito

Installation

Add ex_ratatui to the dependencies in mix.exs:

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

The first compile downloads a precompiled NIF for the host, so no Rust toolchain is needed. Requirements, supported platforms, and building from source are in the Installation guide.

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.

Guides

The guides follow the groups in the docs sidebar. Every runtime works with every transport, and switching transport doesn't change the app module.

• Introduction: Getting Started builds a supervised todo app from mix new and is the place to start. Also Installation, the examples catalog, and Built with ExRatatui.
• Building UIs: Building UIs covers widgets, layout, styles, rich text, and events. Then custom widgets, images, 3D rendering, and paste and clipboard.
• Runtimes: the Callback Runtime (LiveView-style mount/render/handle_event, the default) and the Reducer Runtime (Elm-style update/2 with commands and subscriptions), compared side by side. Also state machine patterns and apps written in Erlang and Gleam.
• Transports: the local terminal by default, or SSH, a remote IEx shell, Erlang distribution, custom transports, and non-terminal surfaces, including pixel displays through raster_ex_ratatui. The Transports guide has the feature matrix.
• Going deeper: Architecture, Testing, Debugging, Performance, and Telemetry.
• Packaging: single-file native binaries with Burrito.
• Cheatsheets: the widgets cheatsheet, every struct with 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.
• raster_ex_ratatui — Run TUIs on pixel displays such as e-ink panels, with helpers for Linux framebuffers.

Built with ExRatatui

Built with ExRatatui lists apps that use it, from Ash and robotics explorers to system monitors and coding agents. Yours? Open a PR.

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.