TermUI

A direct-mode Terminal UI framework for Elixir/BEAM, inspired by BubbleTea (Go) and Ratatui (Rust).

TermUI combines The Elm Architecture with the BEAM process model and supervision primitives to build robust terminal applications.

Features

• Elm Architecture - Predictable state management with init/update/view
• Rich Widget Library - Gauges, tables, menus, charts, dialogs, and more
• Efficient Rendering - A dirty render loop capped at roughly 60 FPS, with differential updates in Raw/custom backends and full-frame TTY redraws
• Themable - True color RGB support (16 million colors)
• Terminal Backends - Raw and TTY operation on Unix terminals, plus remote SSH sessions
• OTP Integration - A supervised runtime plus optional lower-level component lifecycle services
• IEx Compatible - Run TUI applications directly in IEx for interactive development

Platform support

TermUI 1.0's local Raw and TTY backends target Unix-style terminals and are supported on Linux and macOS. The SSH backend renders independent sessions to OTP SSH channel devices.

Native Windows console support is experimental. ANSI output can work in a terminal where virtual-terminal processing is already enabled, but TermUI does not yet configure Win32 console modes or provide native raw input and resize handling. On Windows, prefer WSL and verify keyboard, resize, paste, and cleanup behavior for the terminal you deploy with. Mouse tracking is intentionally disabled under WSL/ConPTY because disabling sequences are not handled reliably.

OTP 26's signal API does not expose SIGWINCH to application handlers. The minimum-version TTY backend still supports size queries, but automatic local resize events require a newer OTP; Raw mode already requires OTP 28 or later.

IEx Compatibility

TermUI applications work directly in IEx with no code changes. This is perfect for:

• Interactive debugging and development
• Admin tools and dashboards in production IEx sessions
• Prototyping and testing TUI interfaces

Running in IEx

# In your IEx session
iex> TermUI.Runtime.run(root: MyApp.Counter)
# Use arrow keys, press Q to quit, returns to IEx prompt

How It Works

TermUI keeps the active IEx shell in cooked mode and reads through its IO server from a dedicated input process. This avoids replacing the shell while still allowing TermUI to parse navigation keys and return cleanly to the IEx prompt. Depending on the shell and terminal driver, cooked input may be delivered immediately or buffered until Enter is pressed.

Detection and Configuration

You can detect if your application is running in IEx:

iex> TermUI.iex_mode?()
true

iex> TermUI.running_mode()
:iex

Force IEx-compatible mode via configuration:

# config/config.exs
config :term_ui,
  iex_compatible: true

Or via environment variable:

export TERM_UI_IEX_MODE=true

Important Notes

• Navigation keys are supported - Some cooked-mode terminals deliver them only after Enter is pressed
• Keyboard shortcuts are parsed - Including Tab, Enter, Escape, and function keys once the shell delivers their bytes
• Clean shutdown - Terminal state is restored when the app exits
• Clean return to IEx - Exiting the TUI restores the prompt for more commands

Widgets

Installation

Add term_ui to your dependencies in mix.exs:

def deps do
  [
    {:term_ui, "~> 1.0"}
  ]
end

Quick Start

defmodule Counter do
  use TermUI.Elm

  alias TermUI.Event
  alias TermUI.Renderer.Style

  def init(_opts), do: %{count: 0}

  def event_to_msg(%Event.Key{key: :up}, _state), do: {:msg, :increment}
  def event_to_msg(%Event.Key{key: :down}, _state), do: {:msg, :decrement}
  def event_to_msg(%Event.Key{key: "q"}, _state), do: {:msg, :quit}
  def event_to_msg(_, _), do: :ignore

  def update(:increment, state), do: {%{state | count: state.count + 1}, []}
  def update(:decrement, state), do: {%{state | count: state.count - 1}, []}
  def update(:quit, state), do: {state, [TermUI.Command.quit()]}

  def view(state) do
    stack(:vertical, [
      text("Counter Example", Style.new(fg: :cyan, attrs: [:bold])),
      text("", nil),
      text("Count: #{state.count}", nil),
      text("", nil),
      text("↑/↓ to change, Q to quit", Style.new(fg: :bright_black))
    ])
  end
end

# Run the application
TermUI.Runtime.run(root: Counter)

Documentation

User Guides

Developer Guides

Examples

The examples/ directory contains standalone applications demonstrating each widget:

# Run any example
cd examples/dashboard
mix deps.get
mix termui.run

Requirements

• Elixir 1.15+
• OTP 26+ for TTY mode; OTP 28+ for native Raw mode
• An ANSI-capable terminal; common widgets support ASCII fallback, while Braille charts and a few legacy/specialized renderers require Unicode (see the compatibility guide)

License

MIT License - see LICENSE for details.