Raxol.LiveView.TerminalComponent (Raxol v2.0.1)

A Phoenix LiveView component for rendering terminal buffers in web browsers.

This component provides high-performance terminal rendering with character-perfect monospace grid alignment, virtual DOM diffing, and built-in theme support.

Features

60fps rendering capability with smart caching
Virtual DOM-style diffing to minimize DOM updates
Character-perfect 1ch monospace grid alignment
7 built-in themes (synthwave84, nord, dracula, monokai, gruvbox, solarized, tokyo_night)
Keyboard and mouse event handling
Accessible (ARIA attributes, screen reader support)
CRT mode with scanline effects
High contrast mode for accessibility

Basic Usage

<.live_component
  module={Raxol.LiveView.TerminalComponent}
  id="terminal"
  buffer={@buffer}
/>

Full Example

<.live_component
  module={Raxol.LiveView.TerminalComponent}
  id="terminal"
  buffer={@buffer}
  theme={:synthwave84}
  width={80}
  height={24}
  crt_mode={false}
  high_contrast={false}
  aria_label="Interactive terminal interface"
  on_keypress="handle_key"
  on_cell_click="handle_cell_click"
/>

# In your LiveView
def handle_event("handle_key", %{"key" => key}, socket) do
  # Process keyboard input
  {:noreply, socket}
end

def handle_event("handle_cell_click", %{"row" => row, "col" => col}, socket) do
  # Process cell click
  {:noreply, socket}
end

Buffer Format

The component expects buffers in this format:

%{
  lines: [
    %{
      cells: [
        %{char: "H", style: %{fg_color: :green, bold: true}},
        %{char: "i", style: %{}}
      ]
    }
  ],
  width: 80,
  height: 24
}

Styles

Each cell's style map supports:

:fg_color - Foreground color (:black, :red, :green, :yellow, :blue, :magenta, :cyan, :white)
:bg_color - Background color (same values as fg_color)
:bold - Bold text (boolean)
:italic - Italic text (boolean)
:underline - Underlined text (boolean)
:reverse - Reverse video (boolean)

Themes

Built-in themes:

:synthwave84 - Retro synthwave colors (default)
:nord - Nordic-inspired theme
:dracula - Popular dark theme
:monokai - Classic editor theme
:gruvbox - Retro groove theme
:solarized_dark - Solarized dark variant
:tokyo_night - Modern dark theme

You can also provide a custom theme map:

theme: %{
  background: "#1a1a1a",
  foreground: "#ffffff",
  cursor: "#00ff00",
  selection: "#333333",
  colors: %{
    black: "#000000",
    red: "#ff0000",
    # ... etc
  }
}

Summary

Functions

handle_event(binary, map, socket)

Handles terminal events (keyboard and cell clicks).

mount(socket)

Initializes the component with a new renderer instance.

render(assigns)

Renders the terminal component HTML.

update(assigns, socket)

Updates the component state with new assigns from the parent LiveView.

Functions

handle_event(binary, map, socket)

Handles terminal events (keyboard and cell clicks).

Events

"keypress"

When :on_keypress assign is set, sends a message to the parent LiveView in the format {:terminal_keypress, component_id, key}.

"cell_click"

When :on_cell_click assign is set, sends a message to the parent LiveView in the format {:terminal_cell_click, component_id, row, col}.

The parent LiveView should implement handlers for these messages to process user interactions with the terminal.

mount(socket)

Initializes the component with a new renderer instance.

Called once when the component is first mounted to the page. Sets up an empty renderer and nil theme CSS which will be populated on first update.

render(assigns)

Renders the terminal component HTML.

Outputs a wrapper div with:

Scoped theme CSS injected as <style> tag
Base CSS for terminal grid layout
CRT mode and high contrast class modifiers
ARIA attributes for accessibility
Keyboard and mouse event handlers
Rendered terminal HTML from buffer

The rendered HTML uses character-perfect 1ch grid alignment with monospace fonts for pixel-perfect terminal display.

update(assigns, socket)

Updates the component state with new assigns from the parent LiveView.

Assigns

Required:

:id - Unique identifier for this component instance

Optional:

:buffer - Terminal buffer to render (creates blank if not provided)
:theme - Theme atom or custom theme map (default: :synthwave84)
:width - Terminal width in characters (default: 80)
:height - Terminal height in characters (default: 24)
:crt_mode - Enable CRT scanline effects (default: false)
:high_contrast - Enable high contrast mode (default: false)
:aria_label - ARIA label for accessibility (default: "Interactive terminal")
:on_keypress - Event name for keyboard events (optional)
:on_cell_click - Event name for cell click events (optional)

Performance

Only regenerates theme CSS when theme changes
Uses renderer's virtual DOM diffing for efficient updates
Caches common character/style combinations