huh

Use huh? to create multi-field interactive forms in the terminal. Forms are composed of Groups (which act as pages), and each group contains Fields (like Select, Input, or Confirm). You can store user answers by passing pointers to variables into the .Value() method of each field. To execute the form, call form.Run().

package main

import (
    "fmt"
    "log"
    "errors"
    "charm.land/huh/v2"
)

var (
    burger       string
    toppings     []string
    sauceLevel   int
    name         string
    instructions string
    discount     bool
)

func main() {
    form := huh.NewForm(
        huh.NewGroup(
            huh.NewSelect[string]().
                Title("Choose your burger").
                Options(
                    huh.NewOption("Charmburger Classic", "classic"),
                    huh.NewOption("Chickwich", "chickwich"),
                ).
                Value(&burger),

            huh.NewMultiSelect[string]().
                Title("Toppings").
                Options(
                    huh.NewOption("Lettuce", "lettuce").Selected(true),
                    huh.NewOption("Cheese", "cheese"),
                ).
                Limit(4).
                Value(&toppings),

            huh.NewSelect[int]().
                Title("How much Charm Sauce?").
                Options(
                    huh.NewOption("None", 0),
                    huh.NewOption("A little", 1),
                ).
                Value(&sauceLevel),
        ),
        huh.NewGroup(
            huh.NewInput().
                Title("What’s your name?").
                Value(&name).
                Validate(func(str string) error {
                    if str == "Frank" {
                        return errors.New("Sorry, we don’t serve customers named Frank.")
                    }
                    return nil
                }),

            huh.NewText().
                Title("Special Instructions").
                CharLimit(400).
                Value(&instructions),

            huh.NewConfirm().
                Title("Would you like 15% off?").
                Value(&discount),
        ),
    )

    err := form.Run()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Order: %s with %v sauce level\n", burger, sauceLevel)
}

huh.Form implements the tea.Model interface, allowing it to be embedded directly into Bubble Tea applications. This is useful for adding form-like input to existing Bubble Tea programs or when you need more flexibility than standalone huh? provides.

To integrate a form:

1. Include a pointer to huh.Form in your application's Model struct.
2. Initialize the form using huh.NewForm() and huh.NewGroup() in your constructor.
3. In your Init() method, return m.form.Init().
4. In your Update() method, call m.form.Update(msg) and update your model with the returned form instance.
5. In your View() method, check m.form.State to determine if the form is completed (huh.StateCompleted) or if you should return m.form.View().
6. Use m.form.GetString(key), m.form.GetInt(key), etc., to retrieve values once the state is completed.

type Model struct {
    form *huh.Form // huh.Form is just a tea.Model
}

func NewModel() Model {
    return Model{
        form: huh.NewForm(
            huh.NewGroup(
                huh.NewSelect[string]().
                    Key("class").
                    Options(huh.NewOptions("Warrior", "Mage", "Rogue")...).
                    Title("Choose your class"),

            huh.NewSelect[int]().
                Key("level").
                Options(huh.NewOptions(1, 20, 9999)...).
                Title("Choose your level"),
            ),
        )
    }
}

func (m Model) Init() tea.Cmd {
    return m.form.Init()
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    // ...

    form, cmd := m.form.Update(msg)
    if f, ok := form.(*huh.Form); ok {
        m.form = f
    }

    return m, cmd
}

func (m Model) View() string {
    if m.form.State == huh.StateCompleted {
        class := m.form.GetString("class")
        level := m.form.GetInt("level")
        return fmt.Sprintf("You selected: %s, Lvl. %d", class, level)
    }
    return m.form.View()
}

You can create forms where fields change based on previous answers by using TitleFunc and OptionsFunc instead of Title and Options.

These functions take a func() T and a binding any. The binding tells huh? which variable to watch; whenever that variable changes, the function is recomputed. This is useful for cascading selects (e.g., selecting a Country then showing only relevant States).

var country string
var state string

// The state field recomputes its title and options whenever 'country' changes
huh.NewSelect[string]().
    Value(&state).
    TitleFunc(func() string {
        switch country {
        case "United States":
            return "State"
        case "Canada":
            return "Province"
        default:
            return "Territory"
        }
    }, &country).
    OptionsFunc(func() []huh.Option[string] {
        // fetchStatesForCountry is a user-defined function
        opts := fetchStatesForCountry(country)
        return huh.NewOptions(opts...)
    }, &country)

To migrate from Huh v1 to v2, you must update your dependencies and change your import paths to use the charm.land vanity domain with a /v2 suffix.

1. Update Dependencies

Run the following commands to update your go.mod:

go get charm.land/huh/v2@latest
go get charm.land/bubbletea/v2@latest
go get charm.land/lipgloss/v2@latest
go get charm.land/bubbles/v2@latest

2. Update Import Paths

Replace all github.com/charmbracelet/ imports with their charm.land/.../v2 equivalents.

3. Migration Checklist

• Update go.mod dependencies to v2
• Update all import paths to charm.land/ with /v2 suffix
• Update theme calls to pass isDark bool parameter
• Remove field-level WithAccessible() calls
• Keep form-level WithAccessible() calls
• Remove imports from github.com/charmbracelet/huh/accessibility package
• Update custom themes to ThemeFunc signature
• Run go mod tidy and tests