TermUI.Widgets.Dialog (TermUI v1.0.0)

View Source

Dialog widget for modal overlays.

Dialog appears centered over the application with a backdrop, traps focus, and handles Escape for cancellation. Use for confirmations, forms, and important messages.

Usage

Dialog.new(
  title: "Confirm Delete",
  content: delete_confirmation_content(),
  buttons: [
    %{id: :cancel, label: "Cancel"},
    %{id: :confirm, label: "Delete", style: :danger}
  ],
  on_close: fn -> dismiss_dialog() end,
  on_confirm: fn button_id -> handle_action(button_id) end
)

Features

  • Centered display with customizable width/height
  • Semi-transparent backdrop
  • Focus trapping (Tab cycles within dialog)
  • Escape to close
  • Button navigation and selection

Keyboard Navigation

  • Tab/Shift+Tab: Move between buttons
  • Enter/Space: Activate focused button
  • Escape: Close dialog

Mouse Support

In raw mode, dialog buttons can be clicked with the mouse. Clicking a button produces the same result as pressing Enter on that button. Mouse events are ignored in TTY mode.

  • Left click on button: Activate the button

Summary

Functions

focus_button(state, button_id)

Sets focus to a specific button.

get_focused_button(state)

Gets the currently focused button ID.

hide(state)

Hides the dialog.

new(opts)

Creates new Dialog widget props.

set_content(state, content)

Updates the dialog content.

set_title(state, title)

Updates the dialog title.

show(state)

Shows the dialog.

visible?(state)

Gets whether the dialog is visible.

Functions

focus_button(state, button_id)

@spec focus_button(map(), term()) :: map()

Sets focus to a specific button.

get_focused_button(state)

@spec get_focused_button(map()) :: term()

Gets the currently focused button ID.

hide(state)

@spec hide(map()) :: map()

Hides the dialog.

new(opts)

@spec new(keyword()) :: map()

Creates new Dialog widget props.

Options

  • :title - Dialog title (required)
  • :content - Dialog body content (render node)
  • :buttons - List of button definitions
  • :width - Dialog width (default: 40)
  • :on_close - Callback when dialog is closed
  • :on_confirm - Callback when button is activated
  • :closeable - Whether Escape closes dialog (default: true)
  • :title_style - Style for title bar
  • :content_style - Style for content area
  • :button_style - Style for buttons
  • :focused_button_style - Style for focused button

set_content(state, content)

@spec set_content(map(), term()) :: map()

Updates the dialog content.

set_title(state, title)

@spec set_title(map(), String.t()) :: map()

Updates the dialog title.

show(state)

@spec show(map()) :: map()

Shows the dialog.

visible?(state)

@spec visible?(map()) :: boolean()

Gets whether the dialog is visible.