Low-level Phoenix LiveView helpers for terminal rendering.
Provides utilities for translating browser keyboard events, building JSON-safe render payloads, and pushing terminal state to the client. Use these when you need full control over the LiveView wiring.
For a higher-level drop-in component, see Ghostty.LiveTerminal.Component.
JavaScript hook
Run mix igniter.install ghostty in your Phoenix app to vendor
ghostty.js into assets/vendor/ghostty.js and wire
GhosttyTerminal into assets/js/app.js.
Summary
Functions
Converts terminal cells into a JSON-safe nested list.
Returns JSON-safe cursor metadata for the visible viewport.
Encodes a terminal focus change event.
Converts a browser key event into an encoded terminal escape sequence.
Converts a browser mouse event into an encoded terminal escape sequence.
Resizes the terminal and optional PTY to the given dimensions.
Writes committed browser text input to the terminal.
Parses browser key event params into a Ghostty.KeyEvent.
Parses browser mouse event params into a Ghostty.MouseEvent.
Returns JSON-safe mouse reporting mode metadata.
Pushes a "ghostty:render" event with the current terminal cells.
Returns a render payload map for push_event/3.
Renders a terminal container <div> with the GhosttyTerminal JS hook.
Functions
@spec cells_payload(GenServer.server()) :: [[list()]]
Converts terminal cells into a JSON-safe nested list.
Cell tuples {grapheme, fg, bg, flags} become [grapheme, fg, bg, flags]
where colors are [r, g, b] or nil.
@spec cursor_payload(GenServer.server()) :: map()
Returns JSON-safe cursor metadata for the visible viewport.
Encodes a terminal focus change event.
@spec handle_key(GenServer.server(), map()) :: {:ok, binary()} | :none
Converts a browser key event into an encoded terminal escape sequence.
Returns {:ok, binary} or :none for unrecognized keys.
@spec handle_mouse(GenServer.server(), map()) :: {:ok, binary()} | :none
Converts a browser mouse event into an encoded terminal escape sequence.
@spec handle_resize( GenServer.server(), pos_integer(), pos_integer(), GenServer.server() | nil ) :: :ok
Resizes the terminal and optional PTY to the given dimensions.
@spec handle_text(GenServer.server(), binary()) :: :ok
Writes committed browser text input to the terminal.
This is intended for paste and IME composition commits.
@spec key_event_from_params(map()) :: Ghostty.KeyEvent.t() | :none
Parses browser key event params into a Ghostty.KeyEvent.
Returns a Ghostty.KeyEvent struct or :none for unrecognized keys.
Examples
key_event_from_params(%{"key" => "Enter"})
#=> %Ghostty.KeyEvent{action: :press, key: :enter}
key_event_from_params(%{"key" => "Dead"})
#=> :none@spec mouse_event_from_params(map()) :: Ghostty.MouseEvent.t() | :none
Parses browser mouse event params into a Ghostty.MouseEvent.
Returns a Ghostty.MouseEvent struct or :none for invalid events.
@spec mouse_payload(GenServer.server()) :: map()
Returns JSON-safe mouse reporting mode metadata.
@spec push_render(Phoenix.LiveView.Socket.t(), String.t(), GenServer.server()) :: Phoenix.LiveView.Socket.t()
Pushes a "ghostty:render" event with the current terminal cells.
The payload includes the element id for multi-terminal filtering.
@spec render_payload(String.t(), GenServer.server()) :: map()
Returns a render payload map for push_event/3.
Includes the component id so the JS hook can filter events
when multiple terminals share a LiveView.
Renders a terminal container <div> with the GhosttyTerminal JS hook.
This is a stateless function component. For a stateful LiveComponent
that handles key events internally, use Ghostty.LiveTerminal.Component.
Supports global HTML attributes via :rest.
Attributes
id(:string) (required)cols(:integer) - Defaults to80.rows(:integer) - Defaults to24.fit(:boolean) - Defaults tofalse.autofocus(:boolean) - Defaults tofalse.class(:string) - Defaults to"".- Global attributes are accepted.