Zero-dependency Elixir TUI framework using the Elm Architecture.

Overview

Tela lets you build interactive terminal applications with a simple, testable callback interface modelled on GenServer and Phoenix.LiveView. The runtime handles raw mode, alternate screen, rendering, and cleanup — your callbacks stay pure and easy to unit-test.

Quickstart

defmodule MyApp do
  use Tela

  @impl Tela
  def init(_args), do: {%{count: 0}, nil}

  @impl Tela
  def handle_event(model, %Tela.Key{key: {:char, "q"}}), do: {model, :quit}
  def handle_event(model, %Tela.Key{key: {:char, " "}}), do: {%{model | count: model.count + 1}, nil}
  def handle_event(model, _key), do: {model, nil}

  @impl Tela
  def handle_info(model, _msg), do: {model, nil}

  @impl Tela
  def view(model), do: Tela.Frame.new("Count: #{model.count}\nPress <space> to increment, q to quit.")
end

  {:ok, _model} = MyApp.run()

Callbacks

All four callbacks are pure functions. You can call them directly in your test suite without starting the runtime.

init/1

Called once with the args passed to run/2. Returns {initial_model, cmd}.

handle_event/2

Called for every parsed keystroke. Receives the current model and a Tela.Key struct. Returns {new_model, cmd}.

handle_info/2

Called for task results and any other messages sent to the runtime process. Returns {new_model, cmd}.

view/1

Called after every state change. Returns a Tela.Frame with the full UI string (lines separated by \n) and an optional cursor position. The runtime diffs against the previous frame and only redraws changed lines, then positions the real terminal cursor if one is specified.

Commands

The cmd returned from handle_event/2 and handle_info/2 can be:

• nil — no side effect.
• :quit — stop the runtime and restore the terminal.
• {:task, fun} — run fun/0 in a new process. The return value is sent back to the runtime as a message and delivered to handle_info/2.

use Tela

use Tela injects the @behaviour declaration and a run/1 convenience function into your module. You still define all four callbacks yourself.