charm-huh

# charmbracelet/huh

Interactive terminal forms and prompts for Go. Built on Bubble Tea.

Import: `charm.land/huh/v2`

## Quick Start

```go
package main

import (
    "fmt"
    "log"

    "charm.land/huh/v2"
)

func main() {
    var name string
    var confirm bool

    err := huh.NewForm(
        huh.NewGroup(
            huh.NewInput().
                Title("What's your name?").
                Value(&name).
                Validate(huh.ValidateNotEmpty()),
            huh.NewConfirm().
                Title("Ready?").
                Value(&confirm),
        ),
    ).Run()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Hello, %s!\n", name)
}
```

Single field shorthand (no Form/Group wrapper needed):

```go
var name string
huh.NewInput().Title("Name?").Value(&name).Run()
```

## Core API

### Architecture

`Form` > `Group` (pages) > `Field` (inputs)

Groups are displayed one at a time. The form advances to the next group when all fields in the current group pass validation.

### Form

```go
form := huh.NewForm(groups...*Group) *Form
```

Key methods:

| Method | Purpose |
|--------|---------|
| `.Run()` | Block and run the form |
| `.RunWithContext(ctx)` | Run with context (supports cancellation) |
| `.WithTheme(theme)` | Set theme |
| `.WithWidth(w)` / `.WithHeight(h)` | Set dimensions |
| `.WithAccessible(bool)` | Screen reader mode |
| `.WithShowHelp(bool)` | Toggle help bar |
| `.WithShowErrors(bool)` | Toggle error display |
| `.WithTimeout(duration)` | Auto-cancel after duration |
| `.WithLayout(layout)` | Set group layout |
| `.WithKeyMap(keymap)` | Custom keybindings |
| `.WithOutput(w)` / `.WithInput(r)` | Custom IO |

Retrieve values by key after completion:

```go
form.GetString("key")
form.GetInt("key")
form.GetBool("key")
form.Get("key") // any
```

Form states: `huh.StateNormal`, `huh.StateCompleted`, `huh.StateAborted`

Errors: `huh.ErrUserAborted` (ctrl+c), `huh.ErrTimeout`

### Group

```go
group := huh.NewGroup(fields ...Field) *Group
```

| Method | Purpose |
|--------|---------|
| `.Title(s)` / `.Description(s)` | Group header |
| `.WithHide(bool)` | Skip this group |
| `.WithHideFunc(func() bool)` | Conditionally skip group |
| `.WithShowHelp(bool)` | Toggle help for group |

### Field Types

Every field supports: `.Title(s)`, `.Description(s)`, `.Key(s)`, `.Value(&v)`, `.Validate(fn)`, `.Run()`.

Dynamic variants exist for most properties: `.TitleFunc(fn, binding)`, `.DescriptionFunc(fn, binding)`, etc.

#### Input

Single line text. Type: `string`.

```go
huh.NewInput().
    Title("Email").
    Placeholder("you@example.com").
    Prompt("> ").
    CharLimit(100).
    Suggestions([]string{"gmail.com", "outlook.com"}).
    EchoMode(huh.EchoModePassword). // or EchoModeNone
    Inline(true). // title and input on same line
    Validate(huh.ValidateNotEmpty()).
    Value(&email)
```

#### Text

Multi-line textarea. Type: `string`.

```go
huh.NewText().
    Title("Description").
    Lines(5).
    CharLimit(500).
    Placeholder("Enter details...").
    ShowLineNumbers(true).
    Editor("vim"). // external editor support (ctrl+e)
    EditorExtension("md").
    ExternalEditor(false). // disable external editor
    Value(&description)
```

#### Select

Pick one from a list. Generic: `Select[T comparable]`.

```go
huh.NewSelect[string]().
    Title("Country").
    Options(
        huh.NewOption("United States", "US"),
        huh.NewOption("Canada", "CA"),
    ).
    Height(8).      // scrollable if options exceed height
    Inline(true).   // horizontal left/right navigation
    Filtering(true). // start with filter active
    Value(&country)
```

Shorthand for simple options:

```go
Options(huh.NewOptions("Warrior", "Mage", "Rogue")...)
```

#### MultiSelect

Pick zero or more. Generic: `MultiSelect[T comparable]`.

```go
huh.NewMultiSelect[string]().
    Title("Toppings").
    Options(
        huh.NewOption("Lettuce", "lettuce").Selected(true),
        huh.NewOption("Tomato", "tomato"),
        huh.NewOption("Cheese", "cheese"),
    ).
    Limit(3).
    Height(6).
    Filterable(false). // disable "/" filter
    Value(&toppings)
```

Space to toggle, `a` to select all (when no limit), `/` to filter.

#### Confirm

Yes/No. Type: `bool`.

```go
huh.NewConfirm().
    Title("Continue?").
    Affirmative("Yes!").
    Negative("No way").
    Inline(true).
    Value(&ok)
```

Keys: `h`/`l` or left/right to toggle, `y` to accept, `n` to reject.

#### Note

Display-only. Not interactive by default (auto-skipped).

```go
huh.NewNote().
    Title("Welcome").
    Description("This form collects your _preferences_.").
    Height(10).
    Next(true).        // show a "Next" button, makes it interactive
    NextLabel("Continue")
```

Description supports basic markdown: `_italic_`, `*bold*`, `` `code` ``.

## Common Patterns

### Multi-Step Forms

Groups act as pages. Users navigate forward/back between them.

```go
huh.NewForm(
    huh.NewGroup(/* step 1 fields */).Title("Step 1"),
    huh.NewGroup(/* step 2 fields */).Title("Step 2"),
    huh.NewGroup(/* step 3 fields */).Title("Step 3"),
).Run()
```

### Conditional Groups

Hide groups based on previous answers:

```go
var wantExtras bool

huh.NewForm(
    huh.NewGroup(
        huh.NewConfirm().Title("Want extras?").Value(&wantExtras),
    ),
    huh.NewGroup(
        huh.NewInput().Title("Extra details").Value(&details),
    ).WithHideFunc(func() bool { return !wantExtras }),
).Run()
```

### Dynamic Fields

Use `*Func` variants to recompute properties when bindings change. Pass a pointer to the bound variable.

```go
var country string

huh.NewSelect[string]().
    Value(&state).
    TitleFunc(func() string {
        if country == "Canada" { return "Province" }
        return "State"
    }, &country).
    OptionsFunc(func() []huh.Option[string] {
        return huh.NewOptions(statesByCountry[country]...)
    }, &country)
```

The binding (`&country`) tells huh when to recompute. Results are cached per binding hash.

### Validation

Built-in validators:

```go
huh.ValidateNotEmpty()
huh.ValidateMinLength(3)
huh.ValidateMaxLength(100)
huh.ValidateLength(3, 100)  // min and max
huh.ValidateOneOf("a", "b", "c")
```

Custom validation:

```go
.Validate(func(s string) error {
    if !strings.Contains(s, "@") {
        return fmt.Errorf("must be a valid email")
    }
    return nil
})
```

Validation runs on blur (when leaving a field). Forms block progression if any field in the current group has errors.

### Theming

Built-in themes: `ThemeCharm` (default), `ThemeDracula`, `ThemeCatppuccin`, `ThemeBase16`, `ThemeDefault`.

```go
form.WithTheme(huh.ThemeFunc(huh.ThemeDracula))
```

Custom theme - implement the `Theme` interface:

```go
type Theme interface {
    Theme(isDark bool) *Styles
}
```

Or use `ThemeFunc`:

```go
form.WithTheme(huh.ThemeFunc(func(isDark bool) *huh.Styles {
    s := huh.ThemeCharm(isDark) // start from a base
    s.Focused.Title = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("212"))
    return s
}))
```

### Layouts

```go
form.WithLayout(huh.LayoutDefault)         // one group at a time (default)
form.WithLayout(huh.LayoutStack)           // all groups stacked vertically
form.WithLayout(huh.LayoutColumns(2))      // groups in 2 columns
form.WithLayout(huh.LayoutGrid(2, 3))      // 2 rows, 3 columns
```

### Accessibility

```go
accessible := os.Getenv("ACCESSIBLE") != ""
form.WithAccessible(accessible)
```

When `TERM=dumb`, accessible mode activates automatically. Replaces TUI with plain text prompts. Timeout is not supported in accessible mode.

### Spinner

Separate package for loading indicators after form submission:

```go
import "charm.land/huh/v2/spinner"

err := spinner.New().
    Title("Processing...").
    Action(func() { /* do work */ }).
    Run()
```

Or with context:

```go
go doWork()
spinner.New().Title("Working...").Context(ctx).Run()
```

## Integration: Standalone vs Bubble Tea

### Standalone

Call `.Run()` on a form or individual field. Blocks until complete.

```go
form.Run()
// or
huh.NewInput().Title("Name?").Value(&name).Run()
```

### Embedded in Bubble Tea

`*huh.Form` implements `tea.Model`. Use it as a component in your Bubble Tea app.

```go
type Model struct {
    form *huh.Form
}

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"),
            ),
        ),
    }
}

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
    }

    if m.form.State == huh.StateCompleted {
        return m, tea.Quit
    }
    return m, cmd
}

func (m Model) View() string {
    if m.form.State == huh.StateCompleted {
        return fmt.Sprintf("You picked: %s", m.form.GetString("class"))
    }
    return m.form.View()
}
```

Key differences when embedded:
- Do NOT call `.Run()`, use Init/Update/View cycle instead
- Set `SubmitCmd` and `CancelCmd` if you want custom behavior on form completion
- Use `.Key("name")` on fields, retrieve with `form.GetString("name")`
- Check `form.State` to know when the form is done
- Type assert the Update result: `form.(*huh.Form)`

Navigation methods available for programmatic control:
- `form.NextGroup()`, `form.PrevGroup()`
- `form.NextField()`, `form.PrevField()`
- `form.GetFocusedField()`

## Common Mistakes

1. **Forgetting `.Value(&v)`** - Without it, answers go nowhere. The field uses an internal `EmbeddedAccessor` that you cannot read after form completes unless you use `.Key()` + `form.GetString()`.

2. **Using `.Run()` inside Bubble Tea** - Never call `.Run()` on an embedded form. Use the Init/Update/View pattern.

3. **Missing type parameter on Select/MultiSelect** - `huh.NewSelect[string]()` not `huh.NewSelect()`. The generic parameter determines the option value type.

4. **Dynamic binding without pointer** - `TitleFunc(fn, country)` will not work. Must be `TitleFunc(fn, &country)` with a pointer so huh can detect changes.

5. **Timeout in accessible mode** - `WithTimeout()` returns `ErrTimeoutUnsupported` in accessible mode. Guard it.

6. **Not handling ErrUserAborted** - `form.Run()` returns `huh.ErrUserAborted` when user presses ctrl+c. Always check the error.

7. **Form outputs to stderr** - By default, the TUI renders to stderr (stdout stays clean for piping). Use `.WithOutput(os.Stdout)` to change.

## Checklist

- [ ] Import `charm.land/huh/v2`
- [ ] Every field that stores data has `.Value(&var)` or `.Key("name")`
- [ ] Custom validators return `nil` on success, `error` on failure
- [ ] Dynamic fields use `*Func` variants with pointer bindings
- [ ] Accessible mode handled via env var or config flag
- [ ] `ErrUserAborted` handled after `.Run()`
- [ ] Embedded forms use Init/Update/View, not `.Run()`
- [ ] Form state checked via `form.State == huh.StateCompleted`