Modal

Key bindings

Key	Action
Enter	Fire onSubmit
Esc	Fire onCancel if set, otherwise close

Sizing

Modals auto-size between MinWidth/MinHeight and MaxWidth/MaxHeight. Set both Width and Height for a fixed-size modal. The centering math runs on every Draw so the modal stays centered when the terminal is resized.

Backdrop

Set Backdrop: true in ModalConfig to draw a dark semi-transparent overlay behind the modal. The default modal behavior (DefaultModalBehavior) enables the backdrop by default.

nav.ModalComponent

Modal implements nav.ModalComponent. When pushed via nav.Pages.PushModal, the navigator automatically: captures all input, restores focus on dismiss, and pops on Esc. Custom sub-dialogs can embed Modal and call WrapInputHandler to handle additional keys before the base handler runs.

catppuccin-frappecatppuccin-lattecatppuccin-macchiatocatppuccin-mochadraculadracula-lighteverforest-darkeverforest-lightgithub-darkgithub-lightgruvbox-darkgruvbox-lightkanagawamonokainordonedarkonelightrosepinerosepine-dawnrosepine-moonsolarized-darksolarized-lighttokyonight-daytokyonight-moontokyonight-nighttokyonight-storm

Modal is a configurable modal dialog with centered positioning. Modal implements the nav.ModalComponent interface for automatic lifecycle management.

Constructor func NewAlertModal(title, message string) *Modal

Usage

modal := components.NewModal(components.ModalConfig{
  Title:    "Confirm",
  Width:    50,
  Height:    10,
  Backdrop:  true,
})

modal.SetOnSubmit(func() {
  fmt.Println("Submitted")
})

modal.SetOnCancel(func() {
  fmt.Println("Cancelled")
})

fmt.Println(modal != nil)

Methods

Method	Signature	Description
Cancel	func (m *Modal) Cancel()	Cancel triggers the cancel callback.
Close	func (m *Modal) Close()	Close triggers the close callback.
GetBehavior	func (m *Modal) GetBehavior() ModalBehavior	GetBehavior returns the modal's behavior configuration.
GetHintBar	func (m *Modal) GetHintBar() *KeyHintBar	GetHintBar returns the hint bar for direct manipulation.
GetPanel	func (m *Modal) GetPanel() *Panel	GetPanel returns the modal's panel for customization.
HandleKey	func (m *Modal) HandleKey(ev *tcell.EventKey) bool	HandleKey processes a key event for the Modal.
Hints	func (m *Modal) Hints() []KeyHint	Hints returns key binding hints for this modal.
ModalBehavior	func (m *Modal) ModalBehavior() ModalBehavior	ModalBehavior implements nav.Modal. Returns the modal's behavior configuration.
Name	func (m *Modal) Name() string	Name returns the modal title for breadcrumbs.
OnDismiss	func (m *Modal) OnDismiss() bool	OnDismiss implements nav.Modal. Called when the modal is about to be dismissed. Returns false to cancel the dismiss.
SetBehavior	func (m *Modal) SetBehavior(b ModalBehavior) *Modal	SetBehavior configures the modal's behavior.
SetBlockUntilDismissed	func (m *Modal) SetBlockUntilDismissed(block bool) *Modal	SetBlockUntilDismissed prevents other stack operations until dismissed.
SetContent	func (m *Modal) SetContent(content core.Widget) *Modal	SetContent sets the modal's main content.
SetDismissOnEsc	func (m *Modal) SetDismissOnEsc(dismiss bool) *Modal	SetDismissOnEsc sets whether Escape key dismisses the modal.
SetFocusOnShow	func (m *Modal) SetFocusOnShow(p core.Widget) *Modal	SetFocusOnShow sets a specific widget to focus when the modal is shown. This is useful when the content is a container and you want to focus a child.
SetHints	func (m *Modal) SetHints(hints []KeyHint) *Modal	SetHints sets the key hints displayed at bottom.
SetOnCancel	func (m *Modal) SetOnCancel(fn func()) *Modal	SetOnCancel sets callback for cancel action.
SetOnClose	func (m *Modal) SetOnClose(fn func()) *Modal	SetOnClose sets callback when modal closes.
SetOnDismiss	func (m *Modal) SetOnDismiss(fn func() bool) *Modal	SetOnDismiss sets a handler called before the modal is dismissed. Return false from the handler to cancel the dismiss. This is useful for confirming unsaved changes.
SetOnSubmit	func (m *Modal) SetOnSubmit(fn func()) *Modal	SetOnSubmit sets callback for submit action.
Start	func (m *Modal) Start()	Start is called when the modal becomes active.
Stop	func (m *Modal) Stop()	Stop is called when the modal becomes inactive.
Submit	func (m *Modal) Submit()	Submit triggers the submit callback.

Types

type KeyHint struct KeyHint represents a single key binding hint.

Field	Type	Description
Key	string	e.g., "Enter", "Esc", "Space", "j/k"
Description	string	e.g., "Select", "Close", "Toggle"

type KeyHintBar struct KeyHintBar displays key hints in a pill style at the bottom of views/modals.

Field	Type	Description
Hints	[]KeyHint

type ModalBehavior struct ModalBehavior configures how a modal handles input and lifecycle. This is a copy of nav.ModalBehavior to avoid import cycles. The values are copied when implementing nav.ModalComponent.

Field	Type	Description
CapturesAllInput	bool	CapturesAllInput prevents input from reaching underlying views.
DismissOnEsc	bool	DismissOnEsc automatically dismisses the modal when Escape is pressed.
RestoreFocusOnDismiss	bool	RestoreFocusOnDismiss returns focus to the previous component when dismissed.
Backdrop	bool	Backdrop draws a semi-transparent overlay behind the modal.
BlockUntilDismissed	bool	BlockUntilDismissed prevents other stack operations until this modal is dismissed.

type Panel Panel is a container with rounded borders and optional title. It delegates focus and input handling to its content.