How charmbracelet/huh works
Project Type and Purpose
• This is a Go-based, open-source library (not a standalone service) for building interactive, accessible forms and prompts in the terminal (“huh?”), plus a companion spinner sub-package.
• Key use cases:
• Standalone CLI prompts and forms
• Integration into Bubble Tea TUI apps
• Accessibility mode for screen readers
• The spinner for background activity indicators
High-Level Structure Analysis
• Top-level packages and files:
• accessibility.go / internal/accessibility: core accessibility logic
• form.go, group.go, individual field_*.go files: the form builder API
• option.go, selector, layout.go, validate.go: field option management, rendering layout, validation
• run.go: main orchestration of the interactive prompt loop
• theme.go: theming abstraction (Lip Gloss based)
• spinner/: standalone spinner package with its own Go module
• examples/: client code demonstrating usage patterns
• Config/build: go.mod, Makefile, GitHub workflows, lint config
Key Components
A. Core Library (“huh” package)
• Form Builder Layer
• Form
• Group
• Field types (Input, Text, Select, MultiSelect, Confirm)
• Option & Selector Layer
• Option
• internal/selector
• Layout & Rendering
• layout.go
• internal/accessibility (accessible fallback renderer)
• theme.go (Lip Gloss styling)
• Validation & State
• validate.go
• run.go (form lifecycle: Init, Update, View loop)
B. Spinner Sub-Package (huh/spinner)
• Spinner core
• Spinner examples
C. Examples (clients demonstrating forms, dynamic forms, Bubble Tea integration)
D. External Dependencies
• Bubble Tea (TUI framework)
• Lip Gloss (styling)
• Go standard library
• Any other 3rd-party libs defined in go.mod
Relationships and Data Flow
• User’s Program → imports → Core Library
• Core Library:
• Orchestrates Form → Groups → Fields → Options
• On Run(): form.Run() → run.go triggers rendering cycle → layout + theme + accessibility → update user input → field state updates → validation
• Bubble Tea Integration: Form implements tea.Model → integrates into Bubble Tea’s Update/View
• Spinner: distinct module invoked post-form to show background work
Architectural Patterns and Principles
• Modular design by feature (fields, layout, theme, accessibility)
• Separation of concerns: core logic vs. rendering vs. accessibility
• Plugin-style theming (strategies via theme.go)
• Internal packages (internal/) encapsulate selectors and accessibility, not exposed to consumers
• Examples act as “clients” validating API usability