modal

README

Modal

Overlay container with title, body, footer, and a configurable close key.

Install

glyph add modal

This copies modal.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no modal library to keep in sync.

Hello, world

package main

import (
	"fmt"

	"github.com/truffle-dev/glyph/components/modal"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	m := modal.New(theme.Default).
		WithTitle("Unsaved changes").
		WithBody("You have uncommitted edits. Save before quitting?").
		WithFooter("Enter to save · Esc to cancel").
		WithSize(48, 8)
	fmt.Println(m.View())
}

API surface

Package: modal

Types

• CloseMsg
• Modal

Functions and methods

• New
• WithTitle
• WithBody
• WithSize
• WithCloseKey
• WithFooter
• Width
• Height
• ContentWidth
• ContentHeight
• Init
• Update
• View

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0

Notes

Render m.View() into a string, then lipgloss.Place(parentW, parentH, lipgloss.Center, lipgloss.Center, m.View(), lipgloss.WithWhitespaceChars(" ")) over your background. The modal emits modal.CloseMsg on Esc by default.

See also

• examples/showcase — single-binary TUI composing the seven main surfaces
• components/modal/story — runnable story binary (go run -tags glyph_story ./components/modal/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package modal renders a bordered overlay container with an optional inlaid title, framed body, optional footer, and a configurable close key.

The modal owns its own box (title bar, body, footer) and the close-key handler. It does not own its position relative to a parent — that's the parent's job via lipgloss.Place. Keys the modal does not consume are returned untouched so the parent or contained widget can handle them.

Index

• type CloseMsg
• type Modal
  • func New(t theme.Theme) Modal
  • func (m Modal) ContentHeight() int
  • func (m Modal) ContentWidth() int
  • func (m Modal) Height() int
  • func (m Modal) Init() tea.Cmd
  • func (m Modal) Update(msg tea.Msg) (Modal, tea.Cmd)
  • func (m Modal) View() string
  • func (m Modal) Width() int
  • func (m Modal) WithBody(s string) Modal
  • func (m Modal) WithCloseKey(key string) Modal
  • func (m Modal) WithFooter(s string) Modal
  • func (m Modal) WithSize(w, h int) Modal
  • func (m Modal) WithTitle(s string) Modal

Types

type CloseMsg

type CloseMsg struct{}

CloseMsg is emitted when the user presses the configured close key.

type Modal

type Modal struct {
	// contains filtered or unexported fields
}

Modal is a Bubble Tea model for a bordered overlay container.

func New

func New(t theme.Theme) Modal

New constructs a Modal with sensible defaults: 40x10, Esc to close, no title/body/footer.

func (Modal) ContentHeight

func (m Modal) ContentHeight() int

ContentHeight returns the inner usable height (outer height minus two border rows, minus one more if a footer is set).

func (Modal) ContentWidth

func (m Modal) ContentWidth() int

ContentWidth returns the inner usable width (outer width minus two border columns). Callers can use this to size body content before handing it off via WithBody.

func (Modal) Height

func (m Modal) Height() int

Height returns the total outer height including border cells.

func (Modal) Init

func (m Modal) Init() tea.Cmd

Init implements tea.Model. The modal has no autonomous behavior.

func (Modal) Update

func (m Modal) Update(msg tea.Msg) (Modal, tea.Cmd)

Update handles the close key only. Every other message — including other key events — is returned untouched so the parent or contained widget can route it.

func (Modal) View

func (m Modal) View() string

View renders the bordered modal box. Parent overlays it via lipgloss.Place.

func (Modal) Width

func (m Modal) Width() int

Width returns the total outer width including border cells.

func (Modal) WithBody

func (m Modal) WithBody(s string) Modal

WithBody sets the pre-rendered body string the modal frames. Multi-line bodies are split on "\n". Lines wider than the inner content width are truncated by lipgloss.MaxWidth (rune-aware).

func (Modal) WithCloseKey

func (m Modal) WithCloseKey(key string) Modal

WithCloseKey sets the key that emits CloseMsg. Default is "esc". Pass an empty string to disable the close-on-key behavior entirely.

func (Modal) WithFooter

func (m Modal) WithFooter(s string) Modal

WithFooter sets an optional one-line footer rendered just inside the bottom border (e.g. key hints). A non-empty footer subtracts one row from the content area.

func (Modal) WithSize

func (m Modal) WithSize(w, h int) Modal

WithSize sets the total outer width and height (including border cells). Values smaller than the minimum clamp up to (minWidth, minHeight).

func (Modal) WithTitle

func (m Modal) WithTitle(s string) Modal

WithTitle sets an optional title rendered inlaid in the top border.