Documentation
¶
Overview ¶
Package alert provides a modal acknowledgement dialog component. It renders a bordered titled pane with a message body and a single "OK" button, and resolves to a DismissedMsg via tea.Cmd when the user commits.
Use it for "stop and read this" notifications — surfaced errors, destructive-action results, anything the user must acknowledge before continuing. For passive feedback (success notices, transient warnings) prefer the lighter app.Info / app.Error statusbar messages.
The component is meant to be hosted in the standard modal pattern — identical to pkg/confirm. Fixed-size shape:
if s.alertUp {
return layout.ZStack(
baseLayout,
layout.Center(48, 7, layout.Sized(&s.alert)),
)
}
return baseLayout
Autosize shape (set Options.Autosize = true) — the modal measures its message and centers itself inside whatever bounds it gets, so the caller drops the outer Center wrapper:
if s.alertUp {
return layout.ZStack(baseLayout, layout.Sized(&s.alert))
}
return baseLayout
Reach for autosize whenever the message body is dynamic (subprocess stderr, wrapped API errors) — the fixed size clips those. The modal caps at 80% terminal width (40-col floor) × 60% terminal height, word-wraps against the effective width, and scrolls the message region internally when content overflows; the OK button stays pinned to the last inner row throughout.
While the modal is up, the parent screen returns true from IsCapturingKeys() so the app shell suppresses its global keys (q, t, esc-pop) and the modal owns input. The parent forwards every tea.Msg to the alert and matches alert.DismissedMsg in its own Update to dismiss the modal and act.
Keys (always active when the modal is rendered):
enter / space / esc / o / O dismiss
Extra keys in autosize mode when content overflows the viewport (rule 23 — arrows + hjkl are reserved for scroll library-wide):
↑ / k scroll up one line ↓ / j scroll down one line g / G jump to top / bottom ctrl+u / ctrl+d half-page up / down pgup / pgdown page up / down
Index ¶
- type DismissedMsg
- type Model
- func (m Model) Help() []key.Binding
- func (m Model) Init() tea.Cmd
- func (m *Model) SetActiveColor(c lipgloss.TerminalColor)
- func (m *Model) SetDimensions(w, h int)
- func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)
- func (m *Model) SetMessage(s string)
- func (m *Model) SetMessageStyle(s lipgloss.Style)
- func (m *Model) SetOKStyle(s lipgloss.Style)
- func (m *Model) SetTitle(s string)
- func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
- func (m Model) View() string
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DismissedMsg ¶
type DismissedMsg struct{}
DismissedMsg is emitted when the user dismisses the alert.
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model is the alert dialog's exported state.
func New ¶
New constructs an alert dialog. Always renders in the active border state — the modal owns input whenever it's visible.
func (Model) Help ¶
Help returns the keys this dialog responds to. Compose into the parent's Help() while the modal is up so the hint strip reflects the modal context. In autosize mode with overflowing content, the returned set includes the scroll bindings.
func (*Model) SetActiveColor ¶
func (m *Model) SetActiveColor(c lipgloss.TerminalColor)
SetActiveColor updates the active border color.
func (*Model) SetDimensions ¶
SetDimensions resizes the surrounding pane. In autosize mode the given (w, h) are treated as outer bounds — the pane sizes itself to fit the wrapped message content, capped at 80% width / 60% height — and the wrapped-message viewport recomputes so the modal remains responsive to terminal resizes.
func (*Model) SetInactiveColor ¶
func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)
SetInactiveColor updates the inactive border color.
func (*Model) SetMessage ¶
SetMessage updates the body text. Useful when the modal is reused across different errors without rebuilding the model. In autosize mode the modal re-measures and re-centers, and the scroll offset resets to the top so a fresh error surfaces at its first line.
func (*Model) SetMessageStyle ¶
SetMessageStyle updates the body-text style.
func (*Model) SetOKStyle ¶
SetOKStyle updates the button style. Useful when reacting to a theme swap without rebuilding the model.
func (Model) Update ¶
Update dismisses the alert on enter/space/esc/o/O. In autosize mode with overflowing content, arrows / j/k / g/G / ctrl+u/d / PgUp/PgDn scroll the message region while the OK button stays pinned; when content fits, those keys are inert (they never carry a competing verb — rule 23). All dismiss keys remain active in either mode.
Returns a tea.Cmd carrying DismissedMsg on dismissal; the parent screen matches the result in its own Update to dismiss the modal and act. All keys are active — the modal is the only thing focused while it's up.
type Options ¶
type Options struct {
// Width and Height set the pane's outer dimensions. SetDimensions
// overrides these later if the host re-sizes the modal.
Width, Height int
// Title sits on the top border (e.g. "Error", "Notice"). Defaults to
// "alert".
Title string
// Message is the body text shown above the button. Multi-line strings are
// supported; the component does not wrap.
Message string
// OK is the rendered button label. Defaults to "OK".
OK string
// OKStyle styles the dismissal button. Brackets are part of the render.
OKStyle lipgloss.Style
// MessageStyle styles the body text. Defaults to no styling.
MessageStyle lipgloss.Style
// Pane pass-throughs. Unset fields fall back to ThickBorder when active,
// NormalBorder when inactive, and SlotBracketsNone.
ActiveColor lipgloss.TerminalColor
InactiveColor lipgloss.TerminalColor
ActiveBorder lipgloss.Border
InactiveBorder lipgloss.Border
SlotBrackets pane.SlotBracketStyle
// Autosize enables message-content sizing. When true, SetDimensions
// treats (w, h) as the outer bounds (typically the terminal size).
// The modal word-wraps its message, sizes itself to fit — capped at
// 80% width (min 40 cols) and 60% height — and centers within those
// bounds. Content past the height cap scrolls internally with
// arrows / j/k / g/G / ctrl+u/d / PgUp/PgDn; the OK button stays
// pinned to the last inner row regardless of scroll position.
//
// When false (the zero value, preserving the fixed-size shape),
// SetDimensions sets the pane's outer size directly and the caller
// handles centering with layout.Center(w, h, layout.Sized(&m)).
Autosize bool
}
Options configures a new alert dialog. Zero-value fields fall back to defaults; start from theme.Alert() to fill in the color tokens. For an error-styled alert, override ActiveColor with the theme's ErrorBG after calling theme.Alert().
Source Files