Skip to content

charmbracelet/huh

Repository files navigation

Huh?

A simple and powerful library for building interactive forms in the terminal. Powered by Bubble Tea.

Running a taco form

The above example is running from a single Go program (source).

Tutorial

huh? provides a straightforward API to build forms and prompt users for input.

For this tutorial, we're building a Taco order form. Lets start by importing the dependencies that we'll need.

package main

import (
  "log"

  "github.com/charmbracelet/huh"
)

huh allows you to define a form with multiple groups to separate field forms into pages. We will set up a form with three groups for the customer to fill out.

form := huh.NewForm(
    // What's a taco without a shell?
    // We'll need to know what filling to put inside too.
    huh.NewGroup(
        huh.NewSelect[string]().
            Options(
                huh.NewOption("Soft", "soft"),
                huh.NewOption("Hard", "hard"),
            ).
            Title("Shell?").
            Value(&shell),

        huh.NewSelect[string]().
            Options(
                huh.NewOption("Chicken", "chicken"),
                huh.NewOption("Beef", "beef"),
                huh.NewOption("Fish", "fish"),
                huh.NewOption("Beans", "beans"),
            ).
            Title("Base").
            Value(&base),
    ),

    // Prompt for toppings and special instructions.
    // The customer can ask for up to 4 toppings.
    huh.NewGroup(
        huh.NewMultiSelect[string]().
            Options(
                huh.NewOption("Tomatoes", "tomatoes").Selected(true),
                huh.NewOption("Lettuce", "lettuce").Selected(true),
                huh.NewOption("Salsa", "salsa"),
                huh.NewOption("Cheese", "cheese"),
                huh.NewOption("Sour Cream", "sour cream"),
                huh.NewOption("Corn", "corn"),
            ).
            Title("Toppings").
            Limit(4).
            Value(&toppings),
    ),

    // Gather final details for the order.
    huh.NewGroup(
        huh.NewInput().
            Title("What's your name?").
            Value(&name).
            Validate(validateName),

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

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

Finally, we can run the form:

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

Field Reference

Input

huh.NewInput().
    Title("What's for lunch?").
    Prompt("?").
    Validate(isFood).
    Value(&lunch)

Text

huh.NewText().
    Title("Tell me a story.").
    Validate(checkForPlagiarism).
    Value(&story)

Select

huh.NewSelect[string]().
    Title("Pick a country.").
    Options(
        huh.NewOption("United States", "US"),
        huh.NewOption("Germany", "DE"),
        huh.NewOption("Brazil", "BR"),
        huh.NewOption("Canada", "CA"),
    ).
    Value(&country)

Multiple Select

huh.NewMultiSelect[string]().
    Options(
        huh.NewOption("Cheese", "cheese").Selected(true),
        huh.NewOption("Lettuce", "lettuce").Selected(true),
        huh.NewOption("Corn", "corn"),
        huh.NewOption("Salsa", "salsa"),
        huh.NewOption("Sour Cream", "sour cream"),
        huh.NewOption("Tomatoes", "tomatoes"),
    ).
    Title("Toppings").
    Limit(4).
    Value(&toppings)

Confirm

huh.NewConfirm().
    Title("Toppings").
    Affirmative("Yes!").
    Negative("No.").
    Value(&confirm)

Feedback

We'd love to hear your thoughts on this project. Feel free to drop us a note!

Acknowledgments

huh is inspired by the wonderful Survey library by Alec Aivazis.

License

MIT


Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة