A single-line text input component.

Tela.Component.TextInput accepts printable character input and supports cursor navigation, deletion, and optional password masking. It respects focus state — when blurred, key events are ignored and the cursor is hidden.

Usage

defmodule MyApp do
  use Tela
  alias Tela.Component.TextInput
  alias Tela.Frame

  @impl Tela
  def init(_args) do
    ti = TextInput.init(placeholder: "Pikachu", char_limit: 156) |> TextInput.focus()
    {%{input: ti}, TextInput.blink_cmd(ti)}
  end

  @impl Tela
  def handle_event(model, %Tela.Key{key: key}) when key in [:enter, :escape, {:ctrl, "c"}] do
    {model, :quit}
  end

  def handle_event(model, key) do
    {input, cmd} = TextInput.handle_event(model.input, key)
    {%{model | input: input}, cmd}
  end

  @impl Tela
  def handle_info(model, msg) do
    {input, cmd} = TextInput.handle_blink(model.input, msg)
    {%{model | input: input}, cmd}
  end

  @impl Tela
  def view(model) do
    header = Frame.new("What's your favorite Pokémon?\n\n")
    footer = Frame.new("\n\n(esc to quit)")
    Frame.join([header, TextInput.view(model.input), footer], separator: "")
  end
end

Focus

A TextInput is blurred by default. Call focus/1 to enable input and show the cursor. Call blur/1 to hide the cursor and stop accepting key events. In a multi-field form, only one input should be focused at a time.

Cursor

TextInput uses a virtual cursor — a reverse-video character embedded directly in the content string at the cursor position. The frame returned by view/1 always has cursor: nil; the real terminal cursor is kept hidden so it does not overwrite the virtual cursor's colour.

The cursor character is the grapheme under the cursor (or a space when the cursor is past the last grapheme), rendered with Style.reverse(focused_style). This produces a coloured reverse-video block that inherits the focused colour.

Cursor visibility is controlled by cursor_mode:

• :blink — the cursor blinks on and off every 530 ms (default). The application timer drives this by toggling cursor_visible, which gates whether the reverse-video character appears in content.
• :static — the cursor is always visible.
• :hidden — no cursor character is embedded in content.

Use blink_cmd/1 to start the blink loop and handle_blink/2 to process tick messages. The stale-tick guard (same pattern as Tela.Component.Spinner) ensures that in-flight blink tasks from a previous mode or replaced input are silently discarded. Use set_cursor_mode/2 to change modes at runtime.

Echo modes

Set echo_mode: to control how the value is displayed:

• :normal — characters rendered as typed (default).
• :password — each character replaced by echo_char (default "*"). Pass echo_char: "•" for a bullet. The underlying value is stored unmasked and returned by value/1.
• :none — nothing is rendered; the input acts as a fully invisible field. Useful for pinentry-style inputs. The underlying value is still stored and returned unmasked by value/1.

Styling

focused_style and blurred_style are Tela.Style.t() values applied to the prompt and text depending on focus state. Both default to Tela.Style.new().