beamtea 🍵

A delightful terminal UI framework for the BEAM — Bubble Tea for Erlang.

beamtea brings The Elm Architecture to the terminal, built directly on OTP's prim_tty. You write three pure functions — init, update, view — and beamtea handles raw input, UTF-8 decoding, the alternate screen, resizing, timers, and a clean exit. It ships with bubbles: a set of high-level, reusable components inspired by charmbracelet/bubbles, styled with an electric, Charm-inspired colour palette.

-module(counter).
-behaviour(beamtea).
-export([main/0, init/1, update/2, view/1]).

main() -> beamtea:start(?MODULE).

init(_Flags) -> {0, beamtea:none()}.

update({key, up},           N) -> {N + 1, beamtea:none()};
update({key, down},         N) -> {N - 1, beamtea:none()};
update({key, {char, $q}},   N) -> {N, beamtea:quit()};
update(_Msg,                N) -> {N, beamtea:none()}.

view(N) ->
    ["\n  ", beamtea_color:fg(charmple, beamtea_term:bold(<<"counter">>)),
     "\n\n  ", integer_to_binary(N),
     "\n\n  ", beamtea_term:faint(<<"↑ up · ↓ down · q quit"/utf8>>), "\n"].

Status — v0.1.1

Everything below is implemented and covered by tests (103 EUnit cases) plus PTY integration checks on macOS and Linux:

Requires Erlang/OTP 28+ (developed against OTP 29) and rebar3. CI runs the suite on Ubuntu (OTP 28 & 29) and macOS on every push to main and every pull request.

Install

Add beamtea as a rebar3 dependency:

%% rebar.config
{deps, [{beamtea, {git, "https://github.com/tsirysndr/beamtea.git", {tag, "0.1.1"}}}]}.

Or clone and build locally:

git clone https://github.com/tsirysndr/beamtea.git
cd beamtea
rebar3 compile
rebar3 eunit

Running a program

Important: a full-screen TUI needs to own the terminal. Don't launch beamtea programs from inside rebar3 shell — the interactive Erlang shell keeps its own prim_tty on stdin and will fight beamtea for input (you'll see stealing control of fd=0), and Ctrl-C will hit the BEAM break handler.

Use the included launcher, which sets the terminal up correctly and restores it on exit:

./bin/beamtea-run counter
# or
make run EXAMPLE=counter

Under the hood the launcher runs:

stty -isig -ixon                       # Ctrl-C / Ctrl-S arrive as bytes, not signals
erl +Bi -noshell -noinput ... \        # disable the break handler; own the terminal
    -eval "counter:main(), halt()."

To ship your own app, do the same three things (or copy bin/beamtea-run): stty -isig, erl +Bi -noshell -noinput, and call beamtea:start/1.

The Elm Architecture

A beamtea program is three functions. Provide them as a module implementing the beamtea behaviour, or as a map #{init => F, update => F, view => F}.

init(Flags)        -> {Model, Cmd}.   %% initial model + first command
update(Msg, Model) -> {Model, Cmd}.   %% fold a message into the model
view(Model)        -> iodata().       %% render the whole screen

Messages

update/2 receives, from the runtime:

• {key, Key} — a keypress (see Keys below)
• {resize, {Cols, Rows}} — the terminal was resized

…plus any message produced by the commands you return.

Commands

Return a command from init/2 or update/2 to ask the runtime to do something:

Keys

beamtea_key decodes raw bytes into ergonomic key events:

• Named atoms: up, down, left, right, enter, esc, tab, back_tab, backspace, delete, insert, home, 'end', page_up, page_down
• {ctrl, Letter} — e.g. Ctrl-C is {ctrl, $c}
• {char, CodePoint} — a printable character, including space; a full Unicode code point so UTF-8 "just works" (build text with <<Text/binary, CodePoint/utf8>>)

Options

beamtea:start(Program, Flags, Opts):

• alt_screen => boolean() (default true) — use the alternate screen buffer
• catch_ctrl_c => boolean() (default true) — quit on Ctrl-C instead of passing it to update/2
• layout => top_left | center | {place, Opts} (default top_left) — position the whole view within the terminal (see Filling the terminal below)

Filling the terminal

beamtea renders exactly what view/1 returns, anchored top-left — so a small view sits in the corner and the rest of the screen is blank. To use the whole terminal you have two options:

1. Let the runtime place your view — the simplest way to centre or corner-pin a view. The runtime knows the terminal size and re-flows on resize:

beamtea:start(?MODULE, undefined, #{layout => center}).
%% or: #{layout => {place, #{halign => center, valign => bottom}}}

(All the examples use #{layout => center} — that's why they fill the screen.)

2. Lay out yourself — for real full-screen UIs (headers, footers, sidebars). Your update/2 receives the terminal size as {resize, {Cols, Rows}} — including once at startup, before the first frame — so store it and build your view/1 to those dimensions. beamtea_layout (place/3, center/2, top_center/2) and beamtea_util:visible_width/1 (ANSI-aware) help you position and size content.

init(_) -> {#st{w = 80, h = 24}, beamtea:none()}.
update({resize, {W, H}}, St) -> {St#st{w = W, h = H}, beamtea:none()};
%% ...
view(#st{w = W, h = H} = St) ->
    beamtea_layout:center(my_panel(St), {W, H}).

Bubbles — reusable components

Each bubble is a self-contained mini-program (new, update, view, plus accessors). Compose them: keep the bubble's model inside yours, forward messages to its update/2, and embed its view/1. Components that animate (spinner, timer, …) keep themselves running by re-scheduling their own tick — start them once from init/1.

Example — wiring a spinner into your program:

init(_) ->
    S = beamtea_spinner:new(dot),
    {#st{spin = S}, beamtea_spinner:tick(S)}.        %% start animating

update(Msg, St) ->
    {S1, Cmd} = beamtea_spinner:update(Msg, St#st.spin),
    {St#st{spin = S1}, Cmd}.

view(St) ->
    [beamtea_spinner:view(St#st.spin), " loading..."].

Examples

Build once with rebar3 as examples compile, then run any of these with the launcher:

./bin/beamtea-run <name>

Most examples quit with q; the text-entry demos (textinput_demo, textarea_demo) quit with Esc or Ctrl-C.

Colours

beamtea_color provides an electric, Charm-inspired palette mapped to xterm-256 indices. Reference a colour by name:

beamtea_color:fg(hotpink, "hi")                     %% named foreground
beamtea_term:paint([38, 5, beamtea_color:c(charmple)], "hi")

Names include charmple, purple, indigo, violet, hotpink, pink, magenta, cyan, aqua, teal, blue, green, lime, mint, yellow, gold, orange, coral, red, and neutrals (cloud, gray, dim, charcoal). See beamtea_color:names/0.

Low-level escapes live in beamtea_term: alt_enter/0, hide_cursor/0, move/2, sgr/1, bold/1, faint/1, reverse/1, paint/2, …

Tip: always tag non-ASCII binary literals with /utf8 — <<"↑ up"/utf8>>, not <<"↑ up">>. Without it the compiler byte-truncates each code point into garbage. beamtea's renderer also accepts plain Unicode code-point lists ("↑ up"), so either works.

Testing

rebar3 eunit        # 103 unit tests (pure logic: key parsing, rendering, commands, every bubble)
rebar3 xref         # cross-reference checks

The unit tests are pure and run identically on Linux and macOS. Terminal behaviour (raw mode, alt screen, arrow keys, UTF-8, Ctrl-C, clean restore) is verified separately by driving real programs through a PTY.

Documentation

Every module is annotated with @doc/-spec. Generate browsable HTML API docs into ./doc:

rebar3 edoc         # or: make docs
open doc/index.html

Project layout

src/
  beamtea.erl            public API, behaviour, command constructors
  beamtea_runtime.erl    the event loop that owns the terminal
  beamtea_key.erl        raw bytes -> key events
  beamtea_term.erl       ANSI / VT escape sequences
  beamtea_render.erl     full-frame rendering
  beamtea_cmd.erl        command -> effects (pure)
  beamtea_color.erl      electric colour palette
  beamtea_util.erl       shared helpers (time formatting, padding, ANSI width)
  beamtea_*.erl          the bubbles (spinner, textinput, table, …)
examples/                runnable example programs
bin/beamtea-run          the launcher
test/                    EUnit suites

Why a launcher, and how Ctrl-C works

prim_tty's raw mode keeps ISIG enabled — exactly as the Erlang shell does — so Ctrl-C would normally become a SIGINT handled by the BEAM break handler (BREAK: (a)bort ...), hanging the UI. The BEAM reserves SIGINT (you cannot os:set_signal(sigint, handle)), so beamtea instead:

1. runs with +Bi to disable the break handler, and
2. disables ISIG on the terminal (via stty -isig in the launcher) so Ctrl-C arrives as a plain 0x03 byte.

prim_tty preserves that setting, so the runtime sees {ctrl, $c} and quits cleanly, restoring cooked mode, the cursor, and the primary screen on the way out. Running with -noshell -noinput makes beamtea the sole owner of stdin, avoiding any conflict with the interactive shell.

License

MIT © 2026 Tsiry Sandratraina. See LICENSE.