# charmbracelet/huh architecture

> Architecture diagram of the GitHub repository charmbracelet/huh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charmbracelet/huh
- Repository: https://github.com/charmbracelet/huh

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Applications
    subgraph "Client Applications" 
        Examples["Examples"]:::client
    end

    %% Core Library
    subgraph "huh Core Library"
        CoreEntry["Core Entry Point\n(huh.go)"]:::public
        FormOrch["Form Orchestration\n(form.go)"]:::public
        LifecycleRunner["Lifecycle Runner\n(run.go)"]:::public
        GroupMgr["Group Manager\n(group.go)"]:::public

        subgraph "Field Types"
            InputField["Input Field\n(field_input.go)"]:::public
            TextField["Text Field\n(field_text.go)"]:::public
            SelectField["Select Field\n(field_select.go)"]:::public
            MultiSelectField["MultiSelect Field\n(field_multiselect.go)"]:::public
            ConfirmField["Confirm Field\n(field_confirm.go)"]:::public
            FilePickerField["FilePicker Field\n(field_filepicker.go)"]:::public
            NoteField["Note Field\n(field_note.go)"]:::public
        end

        subgraph "Option & Selector"
            OptionLayer["Option Layer\n(option.go)"]:::public
            SelectorLayer["Internal Selector\n(internal/selector/selector.go)"]:::internal
        end

        subgraph "Layout & Rendering"
            Layout["Layout\n(layout.go)"]:::public
            Theme["Theme\n(theme.go)"]:::public
            Wrap["Wrap\n(wrap.go)"]:::public
        end

        subgraph "Accessibility"
            AccPublic["Accessibility API\n(accessibility.go)"]:::public
            AccInternal["Internal Accessibility\n(internal/accessibility/accessibility.go)"]:::internal
        end

        Validation["Validation\n(validate.go)"]:::public
    end

    %% Spinner Module
    subgraph "Spinner Module"
        SpinnerCore["Spinner Core\n(spinner/spinner.go)"]:::public
        SpinnerExamples["Spinner Examples"]:::client
    end

    %% External Dependencies
    subgraph "External Dependencies"
        BubbleTea["Bubble Tea"]:::external
        LipGloss["Lip Gloss"]:::external
        GoStd["Go Stdlib"]:::external
    end

    Terminal["Terminal I/O"]:::external

    %% Dependencies and Data Flow
    Examples -->|imports| CoreEntry
    Examples -->|imports| SpinnerCore

    CoreEntry --> FormOrch
    FormOrch --> LifecycleRunner
    FormOrch --> GroupMgr
    FormOrch --> OptionLayer
    FormOrch --> Layout
    FormOrch --> Validation

    GroupMgr --> InputField
    GroupMgr --> TextField
    GroupMgr --> SelectField
    GroupMgr --> MultiSelectField
    GroupMgr --> ConfirmField
    GroupMgr --> FilePickerField
    GroupMgr --> NoteField

    OptionLayer --> SelectorLayer

    LifecycleRunner --> Layout
    Layout --> Theme
    Layout --> Wrap
    Theme --> LipGloss
    Layout --> Terminal

    FormOrch -.->|accessibility mode| AccInternal
    AccInternal --> Terminal

    AccessFlag{"Accessibility?\n(decision)"}:::decision
    FormOrch -->|checks| AccessFlag
    AccessFlag -->|yes| AccInternal
    AccessFlag -->|no| Layout

    BubbleTea -->|implements tea.Model| FormOrch

    SpinnerCore --> Terminal

    GoStd --> CoreEntry
    LipGloss -.-> Theme

    %% Lifecycle Loop
    LifecycleRunner -.->|Init → Update → View| LifecycleRunner

    %% Click Events
    click Examples "https://github.com/charmbracelet/huh/tree/main/examples/"
    click CoreEntry "https://github.com/charmbracelet/huh/blob/main/huh.go"
    click FormOrch "https://github.com/charmbracelet/huh/blob/main/form.go"
    click LifecycleRunner "https://github.com/charmbracelet/huh/blob/main/run.go"
    click GroupMgr "https://github.com/charmbracelet/huh/blob/main/group.go"
    click InputField "https://github.com/charmbracelet/huh/blob/main/field_input.go"
    click TextField "https://github.com/charmbracelet/huh/blob/main/field_text.go"
    click SelectField "https://github.com/charmbracelet/huh/blob/main/field_select.go"
    click MultiSelectField "https://github.com/charmbracelet/huh/blob/main/field_multiselect.go"
    click ConfirmField "https://github.com/charmbracelet/huh/blob/main/field_confirm.go"
    click FilePickerField "https://github.com/charmbracelet/huh/blob/main/field_filepicker.go"
    click NoteField "https://github.com/charmbracelet/huh/blob/main/field_note.go"
    click OptionLayer "https://github.com/charmbracelet/huh/blob/main/option.go"
    click SelectorLayer "https://github.com/charmbracelet/huh/blob/main/internal/selector/selector.go"
    click Layout "https://github.com/charmbracelet/huh/blob/main/layout.go"
    click Theme "https://github.com/charmbracelet/huh/blob/main/theme.go"
    click Wrap "https://github.com/charmbracelet/huh/blob/main/wrap.go"
    click AccPublic "https://github.com/charmbracelet/huh/blob/main/accessibility.go"
    click AccInternal "https://github.com/charmbracelet/huh/blob/main/internal/accessibility/accessibility.go"
    click Validation "https://github.com/charmbracelet/huh/blob/main/validate.go"
    click SpinnerCore "https://github.com/charmbracelet/huh/blob/main/spinner/spinner.go"
    click SpinnerExamples "https://github.com/charmbracelet/huh/tree/main/spinner/examples/"

    %% Styles
    classDef public fill:#D6EAF8,stroke:#21618C,stroke-width:2px,rounded:true
    classDef internal fill:#F2F3F4,stroke:#AAAAAA,stroke-width:2px
    classDef client fill:#D5F5E3,stroke:#239B56,stroke-width:2px
    classDef external fill:#FDEBD0,stroke:#B9770E,stroke-width:2px
    classDef decision fill:#FCF3CF,stroke:#B7950B,stroke-width:2px,shape:diamond
```
