#644·lipgloss

Proposal: Flexbox/Grid layout engine for terminal UIs (charm-layout)

Author: junhinhowCreated Apr 1, 2026Updated Apr 1, 2026

Problem

Building complex TUI layouts with lipgloss requires manual calculations:

  • `JoinHorizontal` and `JoinVertical` don't support proportional sizing
  • No way to say "sidebar 30%, main 70%"
  • Terminal resize requires manual recalculation of every dimension
  • No grid system for dashboard-style layouts

Every non-trivial Bubble Tea app reinvents layout logic.

Proposed Solution

charm-layout — a CSS Flexbox-inspired layout engine built on lipgloss.

Flex Layout

go
layout := charmlayout.NewFlex(charmlayout.Row).Gap(1)
layout.Add(sidebar, 0.3)   // 30% width
layout.Add(main, 0.7)      // 70% width
layout.SetSize(termWidth, termHeight)
fmt.Println(layout.Render())

Grid Layout

go
grid := charmlayout.NewGrid(3)  // 3 columns
grid.SetWidth(80)
grid.Add(card1, card2, card3, card4, card5)
fmt.Println(grid.Render())
// ┌──────┐ ┌──────┐ ┌──────┐
// │card1 │ │card2 │ │card3 │
// └──────┘ └──────┘ └──────┘
// ┌──────┐ ┌──────┐
// │card4 │ │card5 │
// └──────┘ └──────┘

Features

  • Flex — Row/Column direction, proportional ratios, configurable gap
  • Grid — N columns, auto-row distribution, equal column widths
  • Responsive — `SetSize()` recalculates everything for terminal resize
  • Composable — flex inside grid, grid inside flex
  • Built on lipgloss rendering

Working POC

https://github.com/junhinhow/charm-layout

Bilingual docs (EN/PT-BR).

Questions

  1. Would this complement lipgloss or conflict with its design philosophy?
  2. Interest in adding alignment (start/center/end/space-between) like CSS?
  3. Should it integrate with Bubble Tea's `WindowSizeMsg` directly?