overlay

bubble-overlay

Composable modals and overlay stacks for Bubble Tea: v1 (View() string + OverlayView / OverlayStack) and v2 (View() tea.View + overlayv2).

Requirements

• Go 1.25+ (this module includes charm.land/bubbletea/v2 alongside Bubble Tea v1.)

Installation

go get github.com/madicen/bubble-overlay

The v2 API lives at import path github.com/madicen/bubble-overlay/v2 (package overlayv2); you still add the root module once.

Which API should I use?

Both paths use the same string compositing for the terminal (overlay.OverlayView, grapheme-aware, ANSI/hyperlink-safe). The v2 stack flattens each child tea.View, composites, then wraps with tea.NewView — see docs/ADR-v2-bridge.md.

Bubble Tea v1 — quick start

import overlay "github.com/madicen/bubble-overlay"

func (m model) View() string {
	main := m.renderMain()
	if !m.showModal {
		return main
	}
	modal := lipgloss.NewStyle().Width(40).Render("…")
	return overlay.OverlayView(main, modal, m.width, m.height, row, col)
}

OverlayStack adds nested modals, dimming, Center / RightDrawer / Fixed, Escape and optional click-outside, optional WindowChrome (title bar, drag, close), and FocusTrap so your base model skips keys/mouse while overlays are open. See examples/simple, examples/confirm, examples/stack, examples/draggable.

Bubble Tea v2 — quick start

import (
	tea "charm.land/bubbletea/v2"
	bov "github.com/madicen/bubble-overlay"
	"github.com/madicen/bubble-overlay/v2"
)

func (m rootModel) View() tea.View {
	w, h := m.width, m.height
	if w == 0 || h == 0 {
		w, h = 80, 25
	}
	v := m.stack.CompositeView(m.mainView, w, h)
	v.AltScreen = true
	return v
}

Run go run examples/v2simple/main.go. Use overlayv2.FocusTrap like v1 FocusTrap for interactive routing.

Usage

bubble-overlay composites a string modal over a string main view without destroying the background. It uses display-cell width (grapheme-aware, aligned with lipgloss) and handles ANSI correctly: a full SGR reset (and hyperlink reset) is inserted immediately before the modal so the main line’s active pen does not bleed into the dialog, then after the modal the pen that belonged at the right edge of the hole is re-applied so long styled runs (e.g. full-width lipgloss bars) still look correct past the cut.

examples/colors shows two styled rows with the modal cutting through them; toggle with space.

Transparency and mask

• OverlayViewWithTransparency: ASCII space (' ') in the modal is treated as transparent so the main view shows through at those cells.
• OverlayViewWithMask: choose a mask rune (e.g. ░); only those cells pass through to the main view — see examples/transparency.

Centering. OverlayViewInCenter(main, modal, viewW, viewH) centers the modal in an arbitrary viewport—full terminal, tab strip, or panel—not “full screen only”. Pass the same viewW / viewH you use when compositing that region. When the region’s bounds match the main string’s grid, use ModalCellSize(main) for viewW / viewH, or call OverlayViewInCenterInMain(main, modal) which does that for you.

Centering helpers measure the modal with ModalCellSize (same rules as OverlayView), not lipgloss.Size, so placement and hit-testing stay aligned.

Context menus: use OverlayViewAtPoint(main, modal, viewW, viewH, anchorTop, anchorLeft) (clamp + composite in one step), or ClampOverlayOriginAtPoint / ClampMenuOrigin + OverlayView. Test hits with CellInModal using post-clamp top/left and ModalCellSize(modal).

For “centered but nudged” (e.g. loading line above a label), use OverlayViewInCenterWithOffset (and transparency/mask variants): offsets apply after centering, then OverlayView clamps.

Helpers OverlayViewInCenter*, OverlayViewInCenterInMain, OverlayViewAtPoint*, and OverlayViewInCenterWithOffset* cover common layouts.

Cookbook

Full-screen vs inner panel. Use WindowSizeMsg width/height as viewW / viewH when the main view fills the terminal. When the overlay sits only over a panel whose string is exactly main, use OverlayViewInCenterInMain(main, modal) or ModalCellSize(main) with OverlayViewInCenter so the viewport matches the panel grid.

Menu under cursor (v1 mouse). Coordinates are zero-based. tea.MouseMsg uses X = column (left) and Y = row (top)—same order as OverlayView(..., top, left) arguments only if you pass anchorTop = msg.Y and anchorLeft = msg.X (row first, then column). Example:

out := overlay.OverlayViewAtPoint(base, menu, w, h, msg.Y, msg.X)
t, l := overlay.ClampMenuOrigin(menu, w, h, msg.Y, msg.X)
mw, mh := overlay.ModalCellSize(menu)
inside := overlay.CellInModal(msg.X, msg.Y, t, l, mw, mh)

Stack vs raw compositing. Prefer OverlayStack / Placement when you want dimming, Escape / click-outside, nested modals, and focus routing (FocusTrap). Use OverlayView (and helpers) when you only need a single hole punch or fully custom update routing.

Draggable window chrome. Set OverlayConfig.WindowChrome (or EnableWindowChrome(title)) to add a bordered tab (offset down/right), drag-by-tab, and an optional [x] close control. Set Resizable: true to drag the right edge, bottom edge, or corner to resize (content should be unframed; chrome draws the border). Set Keyboard: true for Alt+arrow move and Alt+Shift+arrow resize (KeyStep sets cells per keypress, default 1). The title sits on the window’s top edge (│ title ┴────┐), with a small tab cap (┌───┐) on the row above. Customize TabBackground, TabForeground, TabBorder, CenterContent, ContentPadTop, MinWidth, MinHeight, and ChromeMaskRune (default DefaultChromeMaskRune = U+E000 in the Private Use Area, so it can't collide with real content; override if your content actually emits PUA runes — pass-through padding via OverlayViewWithMask). The stack auto-wraps the overlay’s View() unless you call WindowFrame yourself and set AutoWrap: false. Enable mouse in your program (tea.WithMouseAllMotion() on v1). Call stack.View(main, w, h) with the same w/h you use for WindowSizeMsg so chrome hit-testing stays aligned. See examples/draggable.

Stack-pushed model hooks. Stack entries can opt into three small interfaces:

bubblezone compatibility. Modal rows that contain no transparent cells (the common case for chromed bodies, since WindowChrome.AutoWrap only pads padding rows with the mask rune) take a string-splice fast path in overlayLine. That path concatenates the modal substring verbatim, so zero-width CSI sequences like bubblezone's \x1B[<id>z markers survive compositing intact — bubblezone.Scan over stack.View(main, w, h) will still find your zones. Transparent cells force the cellbuf compositor, which drops unknown zero-width sequences as a side effect of re-emitting decoded cell data; keep zone markers out of rows that you intentionally make transparent.

Pass-through mouse routing. Hosts that want their main view to stay clickable while a modal is open (e.g. a long-running progress overlay where the user should still be able to browse the underlying content) can call stack.MouseTargetsTop(msg, w, h) before forwarding to stack.Update. It returns true when the event belongs to the top overlay — coordinates inside the painted modal rect, or any motion / release while a chrome drag or resize gesture is in progress — and false when the host should route the message to its own main model instead. Keyboard events are unaffected; they still go through stack.Update as before, so the modal keeps owning its keymap (Escape, action keys, etc.).

Minimize button. Set WindowChrome.ShowMinimizeButton = true to render a [-] toggle to the left of the close button. Clicking it flips LayerState.Minimized and collapses the window to its tab strip (cap + tab row + flat bottom border) — the body and resize handles disappear, but the chrome stays draggable and the title (including any OverlayTitler dynamic value) stays visible. The glyph flips to [+] when minimized; clicking it again restores the body to its previous content size. Both glyphs share MinimizeButtonWidth so the close button doesn't shift columns between states. The stack notifies the entry model when state toggles, via both an OverlayMinimizedMsg{Minimized: bool} delivered through Update and an optional OverlayMinimizer.OnOverlayMinimize(bool) callback — same dual-signal pattern as OverlayResizer / OverlayResizedMsg.

Double-click to minimize / restore. When ShowMinimizeButton is enabled, two presses on the tab drag area within DoubleClickThreshold (500ms) toggle minimize — mirroring the OS-level title-bar gesture. The chrome cancels the drag the first press kicked off so the window doesn't drift while toggling. The gesture is gated on ShowMinimizeButton for discoverability: without the visible [-]/[+] affordance, a hidden double-click action would be too surprising.

Window (single-modal helper). When you don't need stack semantics, use the Window type from pane.go: pass content, title, and a stable key and it manages chrome, drag, resize, and close for you. Set Window.Configure if you need to override the built-in defaults (CenterContent, MinWidth=32, MinHeight=6, default mask rune): the callback receives the populated OverlayConfig and may mutate any field; WindowChrome.Enabled is forced back on so the render path stays consistent.

Consumer integration (OverlayView hosts)

Single source of truth. Overflow clamping (when the modal is wider or taller than the viewport) is implemented once as ClampOverlayOrigin and used by OverlayView. Hosts that duplicate placement logic for hit-testing should call ClampOverlayOrigin or Placement.ClampedOrigin with the same modalW, modalH, viewW, and viewH they use for compositing—do not reimplement the algorithm.

Placement. Placement.Origin returns coordinates before that overflow clamp (it only pins negative top/left to zero). Placement.ClampedOrigin matches what OverlayView paints. Use ClampedOrigin (or Origin plus ClampOverlayOrigin) whenever coordinates must align with the compositor.

Hit-testing. If you forward tea.MouseMsg (or v2 mouse messages) and compare against a stored overlay rectangle, that rectangle must use post-clamp top/left; comparing against pre-clamp “desired” placement will be wrong when the modal overflows the viewport.

Coordinates. OverlayView top/left are zero-based row and column offsets from the top-left of the view string. Bubble Tea v1 tea.MouseMsg X and Y use the same zero-based cell indexing, so they align directly with ClampOverlayOrigin / CellInModal. For Bubble Tea v2, use the X / Y from the underlying mouse event the same way once your pipeline uses the same width/height as compositing.

Helpers. ModalCellSize, CellInModal, CellInTitleBar, and CellInCloseButton are thin exports over the same helpers used by OverlayStack for modal bounds and chrome hit-testing.

Behavioral note (sizing). Modal width/height follow strings.Split(modal, "\n") and max lipgloss.Width per line (matching OverlayView), not a trimmed trailing newline. If you change that measurement in the compositor, update internal/layout.ModalCellSize and release notes accordingly.

Checklist when changing the compositor

Before merging overlay geometry or merge behavior changes: exercise resize, modal larger than the terminal, mouse inside vs outside the modal, and zones vs relative coordinates if your app uses them. Call out breaking behavioral changes in release notes (this repo has no auto-generated changelog—document in your release).

Package reference

Examples

go run examples/simple/main.go
go run examples/confirm/main.go
go run examples/form/main.go
go run examples/spinner/main.go
go run examples/colors/main.go
go run examples/transparency/main.go
go run examples/draggable/main.go
go run examples/stack/main.go
OVERLAY_DEV=1 go run examples/stack/main.go
go run examples/v2simple/main.go

Gallery

Confirm	Form	Spinner	Colors	Nested stack	Transparency	Draggable

Recording GIFs (VHS)

Use make gifs from the repo root. Tapes Source "vhs/_env.tape", which clears CI / NO_COLOR and sets TERM=xterm-256color and COLORTERM=truecolor so lipgloss/termenv emit color (termenv otherwise assumes no TTY when CI is set).

Each tape runs go mod download inside Hide before go run ./examples/... so download lines do not appear in the GIF.