huh

package module
v0.0.0-...-cd28240 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2024 License: MIT Imports: 17 Imported by: 0

README

Huh?

Hey there! I'm Glenn!

Latest Release Go Docs Build Status

A simple, powerful library for building interactive forms and prompts in the terminal.

Running a burger form

huh? is easy to use in a standalone fashion, can be integrated into a Bubble Tea application, and contains a first-class accessible mode for screen readers.

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

Tutorial

Let’s build a form for ordering burgers. To start, we’ll import the library and define a few variables where’ll we store answers.

package main

import "github.com/charmbracelet/huh"

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

huh? separates forms into groups (you can think of groups as pages). Groups are made of fields (e.g. Select, Input, Text). We will set up three groups for the customer to fill out.

form := huh.NewForm(
    huh.NewGroup(
        // Ask the user for a base burger and toppings.
        huh.NewSelect[string]().
            Title("Choose your burger").
            Options(
                huh.NewOption("Charmburger Classic", "classic"),
                huh.NewOption("Chickwich", "chickwich"),
                huh.NewOption("Fishburger", "fishburger"),
                huh.NewOption("Charmpossible™ Burger", "charmpossible"),
            ).
            Value(&burger), // store the chosen option in the "burger" variable

        // Let the user select multiple toppings.
        huh.NewMultiSelect[string]().
            Title("Toppings").
            Options(
                huh.NewOption("Lettuce", "lettuce").Selected(true),
                huh.NewOption("Tomatoes", "tomatoes").Selected(true),
                huh.NewOption("Jalapeños", "jalapeños"),
                huh.NewOption("Cheese", "cheese"),
                huh.NewOption("Vegan Cheese", "vegan cheese"),
                huh.NewOption("Nutella", "nutella"),
            ).
            Limit(4). // there’s a 4 topping limit!
            Value(&toppings),

        // Option values in selects and multi selects can be any type you
        // want. We’ve been recording strings above, but here we’ll store
        // answers as integers. Note the generic "[int]" directive below.
        huh.NewSelect[int]().
            Title("How much Charm Sauce do you want?").
            Options(
                huh.NewOption("None", 0),
                huh.NewOption("A little", 1),
                huh.NewOption("A lot", 2),
            ).
            Value(&sauceLevel),
    ),

    // Gather some final details about the order.
    huh.NewGroup(
        huh.NewInput().
            Title("What's your name?").
            Value(&name).
            // Validating fields is easy. The form will mark erroneous fields
            // and display error messages accordingly.
            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),
    ),
)

Finally, run the form:

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

if !discount {
    fmt.Println("What? You didn’t take the discount?!")
}

And that’s it! For more info see the full source for this example as well as the docs.

Field Reference

  • Input: single line text input
  • Text: multi-line text input
  • Select: select an option from a list
  • MultiSelect: select multiple options from a list
  • Confirm: confirm an action (yes or no)

[!TIP] Just want to prompt the user with a single field? Each field has a Run method that can be used as a shorthand for gathering quick and easy input.

var name string

huh.NewInput().
    Title("What's your name?").
    Value(&name).
    Run() // this is blocking...

fmt.Printf("Hey, %s!\n", name)
Input

Prompt the user for a single line of text.

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

Prompt the user for multiple lines of text.

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

Prompt the user to select a single option from a list.

Select field
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

Prompt the user to select multiple (zero or more) options from a list.

Multiselect field
huh.NewMultiSelect[string]().
    Options(
        huh.NewOption("Lettuce", "Lettuce").Selected(true),
        huh.NewOption("Tomatoes", "Tomatoes").Selected(true),
        huh.NewOption("Charm Sauce", "Charm Sauce"),
        huh.NewOption("Jalapeños", "Jalapeños"),
        huh.NewOption("Cheese", "Cheese"),
        huh.NewOption("Vegan Cheese", "Vegan Cheese"),
        huh.NewOption("Nutella", "Nutella"),
    ).
    Title("Toppings").
    Limit(4).
    Value(&toppings)
Confirm

Prompt the user to confirm (Yes or No).

Confirm field
huh.NewConfirm().
    Title("Are you sure?").
    Affirmative("Yes!").
    Negative("No.").
    Value(&confirm)

Accessibility

huh? has a special rendering option designed specifically for screen readers. You can enable it with form.WithAccessible(true).

[!TIP] We recommend setting this through an environment variable or configuration option to allow the user to control accessibility.

accessibleMode := os.Getenv("ACCESSIBLE") != ""
form.WithAccessible(accessibleMode)

Accessible forms will drop TUIs in favor of standard prompts, providing better dictation and feedback of the information on screen for the visually impaired.

Accessible cuisine form

Themes

huh? contains a powerful theme abstraction. Supply your own custom theme or choose from one of the five predefined themes:

  • Charm
  • Dracula
  • Catppuccin
  • Base 16
  • Default

Charm-themed form Dracula-themed form Catppuccin-themed form Base 16-themed form Default-themed form

Themes can take advantage of the full range of Lip Gloss style options. For a high level theme reference see the docs.

Bonus: Spinner

huh? ships with a standalone spinner package. It’s useful for indicating background activity after a form is submitted.

Spinner while making a burger

Create a new spinner, set a title, set the action (or provide a Context), and run the spinner:

Action Style Context Style
err := spinner.New().
    Title("Making your burger...").
    Action(makeBurger).
    Run()

fmt.Println("Order up!")
go makeBurger()

err := spinner.New().
    Type(spinner.Line).
    Title("Making your burger...").
    Context(ctx).
    Run()

fmt.Println("Order up!")

For more on Spinners see the spinner examples and the spinner docs.

What about Bubble Tea?

In addition to its standalone mode, huh? has first-class support for Bubble Tea and can be easily integrated into Bubble Tea applications. It’s incredibly useful in portions of your Bubble Tea application that need form-like input.

Bubble Tea embedded form example

A huh.Form is merely a tea.Model, so you can use it just as you would any other Bubble.

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.GetString("level")
        return fmt.Sprintf("You selected: %s, Lvl. %d", class, level)
    }
    return m.form.View()
}

For more info in using huh? in Bubble Tea applications see the full Bubble Tea example.

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 • نحنُ نحب المصادر المفتوحة

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrUserAborted = errors.New("user aborted")

ErrUserAborted is the error returned when a user exits the form before submitting.

Functions

func Run

func Run(field Field) error

Run runs a single field by wrapping it within a group and a form.

Types

type Confirm

type Confirm struct {
	// contains filtered or unexported fields
}

Confirm is a form confirm field.

func NewConfirm

func NewConfirm() *Confirm

NewConfirm returns a new confirm field.

func (*Confirm) Affirmative

func (c *Confirm) Affirmative(affirmative string) *Confirm

Affirmative sets the affirmative value of the confirm field.

func (*Confirm) Blur

func (c *Confirm) Blur() tea.Cmd

Blur blurs the confirm field.

func (*Confirm) Description

func (c *Confirm) Description(description string) *Confirm

Description sets the description of the confirm field.

func (*Confirm) Error

func (c *Confirm) Error() error

Error returns the error of the confirm field.

func (*Confirm) Focus

func (c *Confirm) Focus() tea.Cmd

Focus focuses the confirm field.

func (*Confirm) GetKey

func (c *Confirm) GetKey() string

GetKey returns the key of the field.

func (*Confirm) GetValue

func (c *Confirm) GetValue() any

GetValue returns the value of the field.

func (*Confirm) Init

func (c *Confirm) Init() tea.Cmd

Init initializes the confirm field.

func (*Confirm) Inline

func (c *Confirm) Inline(inline bool) *Confirm

Inline sets whether the field should be inline.

func (*Confirm) Key

func (c *Confirm) Key(key string) *Confirm

Key sets the key of the confirm field.

func (*Confirm) KeyBinds

func (c *Confirm) KeyBinds() []key.Binding

KeyBinds returns the help message for the confirm field.

func (*Confirm) Negative

func (c *Confirm) Negative(negative string) *Confirm

Negative sets the negative value of the confirm field.

func (*Confirm) Run

func (c *Confirm) Run() error

Run runs the confirm field in accessible mode.

func (*Confirm) Skip

func (*Confirm) Skip() bool

Skip returns whether the confirm should be skipped or should be blocking.

func (*Confirm) String

func (c *Confirm) String() string

func (*Confirm) Title

func (c *Confirm) Title(title string) *Confirm

Title sets the title of the confirm field.

func (*Confirm) Update

func (c *Confirm) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the confirm field.

func (*Confirm) Validate

func (c *Confirm) Validate(validate func(bool) error) *Confirm

Validate sets the validation function of the confirm field.

func (*Confirm) Value

func (c *Confirm) Value(value *bool) *Confirm

Value sets the value of the confirm field.

func (*Confirm) View

func (c *Confirm) View() string

View renders the confirm field.

func (*Confirm) WithAccessible

func (c *Confirm) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the confirm field.

func (*Confirm) WithHeight

func (c *Confirm) WithHeight(height int) Field

WithHeight sets the height of the confirm field.

func (*Confirm) WithKeyMap

func (c *Confirm) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap of the confirm field.

func (*Confirm) WithPosition

func (c *Confirm) WithPosition(p FieldPosition) Field

WithPosition sets the position of the confirm field.

func (*Confirm) WithTheme

func (c *Confirm) WithTheme(theme *Theme) Field

WithTheme sets the theme of the confirm field.

func (*Confirm) WithWidth

func (c *Confirm) WithWidth(width int) Field

WithWidth sets the width of the confirm field.

func (*Confirm) Zoom

func (*Confirm) Zoom() bool

Zoom returns whether the input should be zoomed.

type ConfirmKeyMap

type ConfirmKeyMap struct {
	Next   key.Binding
	Prev   key.Binding
	Toggle key.Binding
	Submit key.Binding
}

ConfirmKeyMap is the keybindings for confirm fields.

type EchoMode

type EchoMode textinput.EchoMode

EchoMode sets the input behavior of the text Input field.

const (
	// EchoNormal displays text as is.
	// This is the default behavior.
	EchoModeNormal EchoMode = EchoMode(textinput.EchoNormal)

	// EchoPassword displays the EchoCharacter mask instead of actual characters.
	// This is commonly used for password fields.
	EchoModePassword EchoMode = EchoMode(textinput.EchoPassword)

	// EchoNone displays nothing as characters are entered.
	// This is commonly seen for password fields on the command line.
	EchoModeNone EchoMode = EchoMode(textinput.EchoNone)
)

type Field

type Field interface {
	// Bubble Tea Model
	Init() tea.Cmd
	Update(tea.Msg) (tea.Model, tea.Cmd)
	View() string

	// Bubble Tea Events
	Blur() tea.Cmd
	Focus() tea.Cmd

	// Errors and Validation
	Error() error

	// Run runs the field individually.
	Run() error

	// Skip returns whether this input should be skipped or not.
	Skip() bool

	// Zoom returns whether this input should be zoomed or not.
	// Zoom allows the field to take focus of the group / form height.
	Zoom() bool

	// KeyBinds returns help keybindings.
	KeyBinds() []key.Binding

	// WithTheme sets the theme on a field.
	WithTheme(*Theme) Field

	// WithAccessible sets whether the field should run in accessible mode.
	WithAccessible(bool) Field

	// WithKeyMap sets the keymap on a field.
	WithKeyMap(*KeyMap) Field

	// WithWidth sets the width of a field.
	WithWidth(int) Field

	// WithHeight sets the height of a field.
	WithHeight(int) Field

	// WithPosition tells the field the index of the group and position it is in.
	WithPosition(FieldPosition) Field

	// GetKey returns the field's key.
	GetKey() string

	// GetValue returns the field's value.
	GetValue() any
}

Field is a primitive of a form.

A field represents a single input control on a form such as a text input, confirm button, select option, etc...

Each field implements the Bubble Tea Model interface.

type FieldPosition

type FieldPosition struct {
	Group      int
	Field      int
	FirstField int
	LastField  int
	GroupCount int
	FirstGroup int
	LastGroup  int
}

FieldPosition is positional information about the given field and form.

func (FieldPosition) IsFirst

func (p FieldPosition) IsFirst() bool

IsFirst returns whether a field is the form's first field.

func (FieldPosition) IsLast

func (p FieldPosition) IsLast() bool

IsLast returns whether a field is the form's last field.

type FieldStyles

type FieldStyles struct {
	Base           lipgloss.Style
	Title          lipgloss.Style
	Description    lipgloss.Style
	ErrorIndicator lipgloss.Style
	ErrorMessage   lipgloss.Style

	// Select styles.
	SelectSelector lipgloss.Style // Selection indicator
	Option         lipgloss.Style // Select options
	NextIndicator  lipgloss.Style
	PrevIndicator  lipgloss.Style

	// FilePicker styles.
	Directory lipgloss.Style
	File      lipgloss.Style

	// Multi-select styles.
	MultiSelectSelector lipgloss.Style
	SelectedOption      lipgloss.Style
	SelectedPrefix      lipgloss.Style
	UnselectedOption    lipgloss.Style
	UnselectedPrefix    lipgloss.Style

	// Textinput and teatarea styles.
	TextInput TextInputStyles

	// Confirm styles.
	FocusedButton lipgloss.Style
	BlurredButton lipgloss.Style

	// Card styles.
	Card      lipgloss.Style
	NoteTitle lipgloss.Style
	Next      lipgloss.Style
}

FieldStyles are the styles for input fields.

type FilePicker

type FilePicker struct {
	// contains filtered or unexported fields
}

FilePicker is a form file file field.

func NewFilePicker

func NewFilePicker() *FilePicker

NewFilePicker returns a new file field.

func (*FilePicker) AllowedTypes

func (f *FilePicker) AllowedTypes(types []string) *FilePicker

AllowedTypes sets the allowed types of the file field. These will be the only valid file types accepted, other files will show as disabled.

func (*FilePicker) Blur

func (f *FilePicker) Blur() tea.Cmd

Blur blurs the file field.

func (*FilePicker) CurrentDirectory

func (f *FilePicker) CurrentDirectory(directory string) *FilePicker

CurrentDirectory sets the directory of the file field.

func (*FilePicker) Description

func (f *FilePicker) Description(description string) *FilePicker

Description sets the description of the file field.

func (*FilePicker) Error

func (f *FilePicker) Error() error

Error returns the error of the file field.

func (*FilePicker) Focus

func (f *FilePicker) Focus() tea.Cmd

Focus focuses the file field.

func (*FilePicker) GetKey

func (f *FilePicker) GetKey() string

GetKey returns the key of the field.

func (*FilePicker) GetValue

func (f *FilePicker) GetValue() any

GetValue returns the value of the field.

func (*FilePicker) Height

func (f *FilePicker) Height(height int) *FilePicker

Height sets the height of the file field. If the number of options exceeds the height, the file field will become scrollable.

func (*FilePicker) Init

func (f *FilePicker) Init() tea.Cmd

Init initializes the file field.

func (*FilePicker) Key

func (f *FilePicker) Key(key string) *FilePicker

Key sets the key of the file field which can be used to retrieve the value after submission.

func (*FilePicker) KeyBinds

func (f *FilePicker) KeyBinds() []key.Binding

KeyBinds returns the help keybindings for the file field.

func (*FilePicker) Run

func (f *FilePicker) Run() error

Run runs the file field.

func (*FilePicker) ShowHidden

func (f *FilePicker) ShowHidden(v bool) *FilePicker

ShowHidden sets whether to show hidden files.

func (*FilePicker) Skip

func (*FilePicker) Skip() bool

Skip returns whether the file should be skipped or should be blocking.

func (*FilePicker) Title

func (f *FilePicker) Title(title string) *FilePicker

Title sets the title of the file field.

func (*FilePicker) Update

func (f *FilePicker) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the file field.

func (*FilePicker) Validate

func (f *FilePicker) Validate(validate func(string) error) *FilePicker

Validate sets the validation function of the file field.

func (*FilePicker) Value

func (f *FilePicker) Value(value *string) *FilePicker

Value sets the value of the file field.

func (*FilePicker) View

func (f *FilePicker) View() string

View renders the file field.

func (*FilePicker) WithAccessible

func (f *FilePicker) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the file field.

func (*FilePicker) WithHeight

func (f *FilePicker) WithHeight(height int) Field

WithHeight sets the height of the file field.

func (*FilePicker) WithKeyMap

func (f *FilePicker) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap on a file field.

func (*FilePicker) WithPosition

func (f *FilePicker) WithPosition(p FieldPosition) Field

WithPosition sets the position of the file field.

func (*FilePicker) WithTheme

func (f *FilePicker) WithTheme(theme *Theme) Field

WithTheme sets the theme of the file field.

func (*FilePicker) WithWidth

func (f *FilePicker) WithWidth(width int) Field

WithWidth sets the width of the file field.

func (*FilePicker) Zoom

func (f *FilePicker) Zoom() bool

Zoom returns whether the input should be zoomed.

type FilePickerKeyMap

type FilePickerKeyMap struct {
	Open     key.Binding
	Close    key.Binding
	GoToTop  key.Binding
	GoToLast key.Binding
	PageUp   key.Binding
	PageDown key.Binding
	Back     key.Binding
	Select   key.Binding
	Up       key.Binding
	Down     key.Binding
	Prev     key.Binding
	Next     key.Binding
	Submit   key.Binding
}

FilePickerKey is the keybindings for filepicker fields.

type Form

type Form struct {
	State FormState
	// contains filtered or unexported fields
}

Form is a collection of groups that are displayed one at a time on a "page".

The form can navigate between groups and is complete once all the groups are complete.

func NewForm

func NewForm(groups ...*Group) *Form

NewForm returns a form with the given groups and default themes and keybindings.

Use With* methods to customize the form with options, such as setting different themes and keybindings.

func (*Form) Errors

func (f *Form) Errors() []error

Errors returns the current groups' errors.

func (*Form) Get

func (f *Form) Get(key string) any

Get returns a result from the form.

func (*Form) GetBool

func (f *Form) GetBool(key string) bool

GetBool returns a result as a string from the form.

func (*Form) GetInt

func (f *Form) GetInt(key string) int

GetInt returns a result as a string from the form.

func (*Form) GetString

func (f *Form) GetString(key string) string

GetString returns a result as a string from the form.

func (*Form) Help

func (f *Form) Help() help.Model

Help returns the current groups' help.

func (*Form) Init

func (f *Form) Init() tea.Cmd

Init initializes the form.

func (*Form) KeyBinds

func (f *Form) KeyBinds() []key.Binding

KeyBinds returns the current fields' keybinds.

func (*Form) NextField

func (f *Form) NextField() tea.Cmd

NextField moves the form to the next field.

func (*Form) NextGroup

func (f *Form) NextGroup() tea.Cmd

NextGroup moves the form to the next group.

func (*Form) PrevField

func (f *Form) PrevField() tea.Cmd

NextField moves the form to the next field.

func (*Form) PrevGroup

func (f *Form) PrevGroup() tea.Cmd

PrevGroup moves the form to the next group.

func (*Form) Run

func (f *Form) Run() error

Run runs the form.

func (*Form) Update

func (f *Form) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the form.

func (*Form) UpdateFieldPositions

func (f *Form) UpdateFieldPositions() *Form

UpdateFieldPositions sets the position on all the fields.

func (*Form) View

func (f *Form) View() string

View renders the form.

func (*Form) WithAccessible

func (f *Form) WithAccessible(accessible bool) *Form

WithAccessible sets the form to run in accessible mode to avoid redrawing the views which makes it easier for screen readers to read and describe the form.

This avoids using the Bubble Tea renderer and instead simply uses basic terminal prompting to gather input which degrades the user experience but provides accessibility.

func (*Form) WithHeight

func (f *Form) WithHeight(height int) *Form

WithHeight sets the height of a form.

func (*Form) WithKeyMap

func (f *Form) WithKeyMap(keymap *KeyMap) *Form

WithKeyMap sets the keymap on a form.

This allows customization of the form key bindings.

func (*Form) WithShowErrors

func (f *Form) WithShowErrors(v bool) *Form

WithShowErrors sets whether or not the form should show errors.

This allows the form groups and fields to show errors when the Validate function returns an error.

func (*Form) WithShowHelp

func (f *Form) WithShowHelp(v bool) *Form

WithShowHelp sets whether or not the form should show help.

This allows the form groups and field to show what keybindings are available to the user.

func (*Form) WithTheme

func (f *Form) WithTheme(theme *Theme) *Form

WithTheme sets the theme on a form.

This allows all groups and fields to be themed consistently, however themes can be applied to each group and field individually for more granular control.

func (*Form) WithWidth

func (f *Form) WithWidth(width int) *Form

WithWidth sets the width of a form.

This allows all groups and fields to be sized consistently, however width can be applied to each group and field individually for more granular control.

type FormState

type FormState int

FormState represents the current state of the form.

const (
	// StateNormal is when the user is completing the form.
	StateNormal FormState = iota

	// StateCompleted is when the user has completed the form.
	StateCompleted

	// StateAborted is when the user has aborted the form.
	StateAborted
)

type Group

type Group struct {
	// contains filtered or unexported fields
}

Group is a collection of fields that are displayed together with a page of the form. While a group is displayed the form completer can switch between fields in the group.

If any of the fields in a group have errors, the form will not be able to progress to the next group.

func NewGroup

func NewGroup(fields ...Field) *Group

NewGroup returns a new group with the given fields.

func (*Group) Description

func (g *Group) Description(description string) *Group

Description sets the group's description.

func (*Group) Errors

func (g *Group) Errors() []error

Errors returns the groups' fields' errors.

func (*Group) Init

func (g *Group) Init() tea.Cmd

Init initializes the group.

func (*Group) Title

func (g *Group) Title(title string) *Group

Title sets the group's title.

func (*Group) Update

func (g *Group) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the group.

func (*Group) View

func (g *Group) View() string

View renders the group.

func (*Group) WithHeight

func (g *Group) WithHeight(height int) *Group

WithHeight sets the height on a group.

func (*Group) WithHide

func (g *Group) WithHide(hide bool) *Group

WithHide sets whether this group should be skipped.

func (*Group) WithHideFunc

func (g *Group) WithHideFunc(hideFunc func() bool) *Group

WithHideFunc sets the function that checks if this group should be skipped.

func (*Group) WithKeyMap

func (g *Group) WithKeyMap(k *KeyMap) *Group

WithKeyMap sets the keymap on a group.

func (*Group) WithShowErrors

func (g *Group) WithShowErrors(show bool) *Group

WithShowErrors sets whether or not the group's errors should be shown.

func (*Group) WithShowHelp

func (g *Group) WithShowHelp(show bool) *Group

WithShowHelp sets whether or not the group's help should be shown.

func (*Group) WithTheme

func (g *Group) WithTheme(t *Theme) *Group

WithTheme sets the theme on a group.

func (*Group) WithWidth

func (g *Group) WithWidth(width int) *Group

WithWidth sets the width on a group.

type Input

type Input struct {
	// contains filtered or unexported fields
}

Input is a form input field.

func NewInput

func NewInput() *Input

NewInput returns a new input field.

func (*Input) Blur

func (i *Input) Blur() tea.Cmd

Blur blurs the input field.

func (*Input) CharLimit

func (i *Input) CharLimit(charlimit int) *Input

CharLimit sets the character limit of the input field.

func (*Input) Description

func (i *Input) Description(description string) *Input

Description sets the description of the input field.

func (*Input) EchoMode

func (i *Input) EchoMode(mode EchoMode) *Input

EchoMode sets the echo mode of the input.

func (*Input) Error

func (i *Input) Error() error

Error returns the error of the input field.

func (*Input) Focus

func (i *Input) Focus() tea.Cmd

Focus focuses the input field.

func (*Input) GetKey

func (i *Input) GetKey() string

GetKey returns the key of the field.

func (*Input) GetValue

func (i *Input) GetValue() any

GetValue returns the value of the field.

func (*Input) Init

func (i *Input) Init() tea.Cmd

Init initializes the input field.

func (*Input) Inline

func (i *Input) Inline(inline bool) *Input

Inline sets whether the title and input should be on the same line.

func (*Input) Key

func (i *Input) Key(key string) *Input

Key sets the key of the input field.

func (*Input) KeyBinds

func (i *Input) KeyBinds() []key.Binding

KeyBinds returns the help message for the input field.

func (*Input) Password deprecated

func (i *Input) Password(password bool) *Input

Password sets whether or not to hide the input while the user is typing.

Deprecated: use EchoMode(EchoPassword) instead.

func (*Input) Placeholder

func (i *Input) Placeholder(str string) *Input

Placeholder sets the placeholder of the text input.

func (*Input) Prompt

func (i *Input) Prompt(prompt string) *Input

Prompt sets the prompt of the input field.

func (*Input) Run

func (i *Input) Run() error

Run runs the input field in accessible mode.

func (*Input) Skip

func (*Input) Skip() bool

Skip returns whether the input should be skipped or should be blocking.

func (*Input) Suggestions

func (i *Input) Suggestions(suggestions []string) *Input

Suggestions sets the suggestions to display for autocomplete in the input field.

func (*Input) Title

func (i *Input) Title(title string) *Input

Title sets the title of the input field.

func (*Input) Update

func (i *Input) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the input field.

func (*Input) Validate

func (i *Input) Validate(validate func(string) error) *Input

Validate sets the validation function of the input field.

func (*Input) Value

func (i *Input) Value(value *string) *Input

Value sets the value of the input field.

func (*Input) View

func (i *Input) View() string

View renders the input field.

func (*Input) WithAccessible

func (i *Input) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the input field.

func (*Input) WithHeight

func (i *Input) WithHeight(height int) Field

WithHeight sets the height of the input field.

func (*Input) WithKeyMap

func (i *Input) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap on an input field.

func (*Input) WithPosition

func (i *Input) WithPosition(p FieldPosition) Field

WithPosition sets the position of the input field.

func (*Input) WithTheme

func (i *Input) WithTheme(theme *Theme) Field

WithTheme sets the theme of the input field.

func (*Input) WithWidth

func (i *Input) WithWidth(width int) Field

WithWidth sets the width of the input field.

func (*Input) Zoom

func (*Input) Zoom() bool

Zoom returns whether the input should be zoomed.

type InputKeyMap

type InputKeyMap struct {
	AcceptSuggestion key.Binding
	Next             key.Binding
	Prev             key.Binding
	Submit           key.Binding
}

InputKeyMap is the keybindings for input fields.

type KeyMap

type KeyMap struct {
	Quit key.Binding

	Confirm     ConfirmKeyMap
	FilePicker  FilePickerKeyMap
	Input       InputKeyMap
	MultiSelect MultiSelectKeyMap
	Note        NoteKeyMap
	Select      SelectKeyMap
	Text        TextKeyMap
}

KeyMap is the keybindings to navigate the form.

func NewDefaultKeyMap

func NewDefaultKeyMap() *KeyMap

NewDefaultKeyMap returns a new default keymap.

type MultiSelect

type MultiSelect[T comparable] struct {
	// contains filtered or unexported fields
}

MultiSelect is a form multi-select field.

func NewMultiSelect

func NewMultiSelect[T comparable]() *MultiSelect[T]

NewMultiSelect returns a new multi-select field.

func (*MultiSelect[T]) Blur

func (m *MultiSelect[T]) Blur() tea.Cmd

Blur blurs the multi-select field.

func (*MultiSelect[T]) Description

func (m *MultiSelect[T]) Description(description string) *MultiSelect[T]

Description sets the description of the multi-select field.

func (*MultiSelect[T]) Error

func (m *MultiSelect[T]) Error() error

Error returns the error of the multi-select field.

func (*MultiSelect[T]) Filterable

func (m *MultiSelect[T]) Filterable(filterable bool) *MultiSelect[T]

Filterable sets the multi-select field as filterable.

func (*MultiSelect[T]) Focus

func (m *MultiSelect[T]) Focus() tea.Cmd

Focus focuses the multi-select field.

func (*MultiSelect[T]) GetKey

func (m *MultiSelect[T]) GetKey() string

GetKey returns the multi-select's key.

func (*MultiSelect[T]) GetValue

func (m *MultiSelect[T]) GetValue() any

GetValue returns the multi-select's value.

func (*MultiSelect[T]) Height

func (m *MultiSelect[T]) Height(height int) *MultiSelect[T]

Height sets the height of the multi-select field.

func (*MultiSelect[T]) Init

func (m *MultiSelect[T]) Init() tea.Cmd

Init initializes the multi-select field.

func (*MultiSelect[T]) Key

func (m *MultiSelect[T]) Key(key string) *MultiSelect[T]

Key sets the key of the select field which can be used to retrieve the value after submission.

func (*MultiSelect[T]) KeyBinds

func (m *MultiSelect[T]) KeyBinds() []key.Binding

KeyBinds returns the help message for the multi-select field.

func (*MultiSelect[T]) Limit

func (m *MultiSelect[T]) Limit(limit int) *MultiSelect[T]

Limit sets the limit of the multi-select field.

func (*MultiSelect[T]) Options

func (m *MultiSelect[T]) Options(options ...Option[T]) *MultiSelect[T]

Options sets the options of the multi-select field.

func (*MultiSelect[T]) Run

func (m *MultiSelect[T]) Run() error

Run runs the multi-select field.

func (*MultiSelect[T]) Skip

func (*MultiSelect[T]) Skip() bool

Skip returns whether the multiselect should be skipped or should be blocking.

func (*MultiSelect[T]) Title

func (m *MultiSelect[T]) Title(title string) *MultiSelect[T]

Title sets the title of the multi-select field.

func (*MultiSelect[T]) Update

func (m *MultiSelect[T]) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the multi-select field.

func (*MultiSelect[T]) Validate

func (m *MultiSelect[T]) Validate(validate func([]T) error) *MultiSelect[T]

Validate sets the validation function of the multi-select field.

func (*MultiSelect[T]) Value

func (m *MultiSelect[T]) Value(value *[]T) *MultiSelect[T]

Value sets the value of the multi-select field.

func (*MultiSelect[T]) View

func (m *MultiSelect[T]) View() string

View renders the multi-select field.

func (*MultiSelect[T]) WithAccessible

func (m *MultiSelect[T]) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the multi-select field.

func (*MultiSelect[T]) WithHeight

func (m *MultiSelect[T]) WithHeight(height int) Field

WithHeight sets the height of the multi-select field.

func (*MultiSelect[T]) WithKeyMap

func (m *MultiSelect[T]) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap of the multi-select field.

func (*MultiSelect[T]) WithPosition

func (m *MultiSelect[T]) WithPosition(p FieldPosition) Field

WithPosition sets the position of the multi-select field.

func (*MultiSelect[T]) WithTheme

func (m *MultiSelect[T]) WithTheme(theme *Theme) Field

WithTheme sets the theme of the multi-select field.

func (*MultiSelect[T]) WithWidth

func (m *MultiSelect[T]) WithWidth(width int) Field

WithWidth sets the width of the multi-select field.

func (*MultiSelect[T]) Zoom

func (*MultiSelect[T]) Zoom() bool

Zoom returns whether the multiselect should be zoomed.

type MultiSelectKeyMap

type MultiSelectKeyMap struct {
	Next         key.Binding
	Prev         key.Binding
	Up           key.Binding
	Down         key.Binding
	HalfPageUp   key.Binding
	HalfPageDown key.Binding
	GotoTop      key.Binding
	GotoBottom   key.Binding
	Toggle       key.Binding
	Filter       key.Binding
	SetFilter    key.Binding
	ClearFilter  key.Binding
	Submit       key.Binding
}

MultiSelectKeyMap is the keybindings for multi-select fields.

type Note

type Note struct {
	// contains filtered or unexported fields
}

Note is a form note field.

func NewNote

func NewNote() *Note

NewNote creates a new note field.

func (*Note) Blur

func (n *Note) Blur() tea.Cmd

Blur blurs the note field.

func (*Note) Description

func (n *Note) Description(description string) *Note

Description sets the description of the note field.

func (*Note) Error

func (n *Note) Error() error

Error returns the error of the note field.

func (*Note) Focus

func (n *Note) Focus() tea.Cmd

Focus focuses the note field.

func (*Note) GetKey

func (n *Note) GetKey() string

GetKey satisfies the Field interface, notes do not have keys.

func (*Note) GetValue

func (n *Note) GetValue() any

GetValue satisfies the Field interface, notes do not have values.

func (*Note) Init

func (n *Note) Init() tea.Cmd

Init initializes the note field.

func (*Note) KeyBinds

func (n *Note) KeyBinds() []key.Binding

KeyBinds returns the help message for the note field.

func (*Note) Next

func (n *Note) Next(show bool) *Note

Next sets whether to show the next button.

func (*Note) Run

func (n *Note) Run() error

Run runs the note field.

func (*Note) Skip

func (n *Note) Skip() bool

Skip returns whether the note should be skipped or should be blocking.

func (*Note) Title

func (n *Note) Title(title string) *Note

Title sets the title of the note field.

func (*Note) Update

func (n *Note) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the note field.

func (*Note) View

func (n *Note) View() string

View renders the note field.

func (*Note) WithAccessible

func (n *Note) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the note field.

func (*Note) WithHeight

func (n *Note) WithHeight(height int) Field

WithHeight sets the height of the note field.

func (*Note) WithKeyMap

func (n *Note) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap on a note field.

func (*Note) WithPosition

func (n *Note) WithPosition(p FieldPosition) Field

WithPosition sets the position information of the note field.

func (*Note) WithTheme

func (n *Note) WithTheme(theme *Theme) Field

WithTheme sets the theme on a note field.

func (*Note) WithWidth

func (n *Note) WithWidth(width int) Field

WithWidth sets the width of the note field.

func (*Note) Zoom

func (n *Note) Zoom() bool

Zoom returns whether the note should be zoomed.

type NoteKeyMap

type NoteKeyMap struct {
	Next   key.Binding
	Prev   key.Binding
	Submit key.Binding
}

NoteKeyMap is the keybindings for note fields.

type Option

type Option[T comparable] struct {
	Key   string
	Value T
	// contains filtered or unexported fields
}

Option is an option for select fields.

func NewOption

func NewOption[T comparable](key string, value T) Option[T]

NewOption returns a new select option.

func NewOptions

func NewOptions[T comparable](values ...T) []Option[T]

NewOptions returns new options from a list of values.

func (Option[T]) Selected

func (o Option[T]) Selected(selected bool) Option[T]

Selected sets whether the option is currently selected.

func (Option[T]) String

func (o Option[T]) String() string

String returns the key of the option.

type Select

type Select[T comparable] struct {
	// contains filtered or unexported fields
}

Select is a form select field.

func NewSelect

func NewSelect[T comparable]() *Select[T]

NewSelect returns a new select field.

func (*Select[T]) Blur

func (s *Select[T]) Blur() tea.Cmd

Blur blurs the select field.

func (*Select[T]) Description

func (s *Select[T]) Description(description string) *Select[T]

Description sets the description of the select field.

func (*Select[T]) Error

func (s *Select[T]) Error() error

Error returns the error of the select field.

func (*Select[T]) Focus

func (s *Select[T]) Focus() tea.Cmd

Focus focuses the select field.

func (*Select[T]) GetKey

func (s *Select[T]) GetKey() string

GetKey returns the key of the field.

func (*Select[T]) GetValue

func (s *Select[T]) GetValue() any

GetValue returns the value of the field.

func (*Select[T]) Height

func (s *Select[T]) Height(height int) *Select[T]

Height sets the height of the select field. If the number of options exceeds the height, the select field will become scrollable.

func (*Select[T]) Init

func (s *Select[T]) Init() tea.Cmd

Init initializes the select field.

func (*Select[T]) Inline

func (s *Select[T]) Inline(v bool) *Select[T]

Inline sets whether the select input should be inline.

func (*Select[T]) Key

func (s *Select[T]) Key(key string) *Select[T]

Key sets the key of the select field which can be used to retrieve the value after submission.

func (*Select[T]) KeyBinds

func (s *Select[T]) KeyBinds() []key.Binding

KeyBinds returns the help keybindings for the select field.

func (*Select[T]) Options

func (s *Select[T]) Options(options ...Option[T]) *Select[T]

Options sets the options of the select field.

func (*Select[T]) Run

func (s *Select[T]) Run() error

Run runs the select field.

func (*Select[T]) Skip

func (*Select[T]) Skip() bool

Skip returns whether the select should be skipped or should be blocking.

func (*Select[T]) Title

func (s *Select[T]) Title(title string) *Select[T]

Title sets the title of the select field.

func (*Select[T]) Update

func (s *Select[T]) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the select field.

func (*Select[T]) Validate

func (s *Select[T]) Validate(validate func(T) error) *Select[T]

Validate sets the validation function of the select field.

func (*Select[T]) Value

func (s *Select[T]) Value(value *T) *Select[T]

Value sets the value of the select field.

func (*Select[T]) View

func (s *Select[T]) View() string

View renders the select field.

func (*Select[T]) WithAccessible

func (s *Select[T]) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the select field.

func (*Select[T]) WithHeight

func (s *Select[T]) WithHeight(height int) Field

WithHeight sets the height of the select field.

func (*Select[T]) WithKeyMap

func (s *Select[T]) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap on a select field.

func (*Select[T]) WithPosition

func (s *Select[T]) WithPosition(p FieldPosition) Field

WithPosition sets the position of the select field.

func (*Select[T]) WithTheme

func (s *Select[T]) WithTheme(theme *Theme) Field

WithTheme sets the theme of the select field.

func (*Select[T]) WithWidth

func (s *Select[T]) WithWidth(width int) Field

WithWidth sets the width of the select field.

func (*Select[T]) Zoom

func (*Select[T]) Zoom() bool

Zoom returns whether the input should be zoomed.

type SelectKeyMap

type SelectKeyMap struct {
	Next         key.Binding
	Prev         key.Binding
	Up           key.Binding
	Down         key.Binding
	HalfPageUp   key.Binding
	HalfPageDown key.Binding
	GotoTop      key.Binding
	GotoBottom   key.Binding
	Left         key.Binding
	Right        key.Binding
	Filter       key.Binding
	SetFilter    key.Binding
	ClearFilter  key.Binding
	Submit       key.Binding
}

SelectKeyMap is the keybindings for select fields.

type Text

type Text struct {
	// contains filtered or unexported fields
}

Text is a form text field. It allows for a multi-line string input.

func NewText

func NewText() *Text

NewText returns a new text field.

func (*Text) Blur

func (t *Text) Blur() tea.Cmd

Blur blurs the text field.

func (*Text) CharLimit

func (t *Text) CharLimit(charlimit int) *Text

CharLimit sets the character limit of the text field.

func (*Text) Description

func (t *Text) Description(description string) *Text

Description sets the description of the text field.

func (*Text) Editor

func (t *Text) Editor(editor ...string) *Text

Editor specifies which editor to use.

The first argument provided is used as the editor command (vim, nvim, nano, etc...) The following (optional) arguments provided are passed as arguments to the editor command.

func (*Text) EditorExtension

func (t *Text) EditorExtension(extension string) *Text

EditorExtension specifies arguments to pass into the editor.

func (*Text) Error

func (t *Text) Error() error

Error returns the error of the text field.

func (*Text) Focus

func (t *Text) Focus() tea.Cmd

Focus focuses the text field.

func (*Text) GetKey

func (t *Text) GetKey() string

GetKey returns the key of the field.

func (*Text) GetValue

func (t *Text) GetValue() any

GetValue returns the value of the field.

func (*Text) Init

func (t *Text) Init() tea.Cmd

Init initializes the text field.

func (*Text) Key

func (t *Text) Key(key string) *Text

Key sets the key of the text field.

func (*Text) KeyBinds

func (t *Text) KeyBinds() []key.Binding

KeyBinds returns the help message for the text field.

func (*Text) Lines

func (t *Text) Lines(lines int) *Text

Lines sets the number of lines to show of the text field.

func (*Text) Placeholder

func (t *Text) Placeholder(str string) *Text

Placeholder sets the placeholder of the text field.

func (*Text) Run

func (t *Text) Run() error

Run runs the text field.

func (*Text) ShowLineNumbers

func (t *Text) ShowLineNumbers(show bool) *Text

ShowLineNumbers sets whether or not to show line numbers.

func (*Text) Skip

func (*Text) Skip() bool

Skip returns whether the textarea should be skipped or should be blocking.

func (*Text) Title

func (t *Text) Title(title string) *Text

Title sets the title of the text field.

func (*Text) Update

func (t *Text) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update updates the text field.

func (*Text) Validate

func (t *Text) Validate(validate func(string) error) *Text

Validate sets the validation function of the text field.

func (*Text) Value

func (t *Text) Value(value *string) *Text

Value sets the value of the text field.

func (*Text) View

func (t *Text) View() string

View renders the text field.

func (*Text) WithAccessible

func (t *Text) WithAccessible(accessible bool) Field

WithAccessible sets the accessible mode of the text field.

func (*Text) WithHeight

func (t *Text) WithHeight(height int) Field

WithHeight sets the height of the text field.

func (*Text) WithKeyMap

func (t *Text) WithKeyMap(k *KeyMap) Field

WithKeyMap sets the keymap on a text field.

func (*Text) WithPosition

func (t *Text) WithPosition(p FieldPosition) Field

WithPosition sets the position information of the text field.

func (*Text) WithTheme

func (t *Text) WithTheme(theme *Theme) Field

WithTheme sets the theme on a text field.

func (*Text) WithWidth

func (t *Text) WithWidth(width int) Field

WithWidth sets the width of the text field.

func (*Text) Zoom

func (*Text) Zoom() bool

Zoom returns whether the note should be zoomed.

type TextInputStyles

type TextInputStyles struct {
	Cursor      lipgloss.Style
	Placeholder lipgloss.Style
	Prompt      lipgloss.Style
	Text        lipgloss.Style
}

TextInputStyles are the styles for text inputs.

type TextKeyMap

type TextKeyMap struct {
	Next    key.Binding
	Prev    key.Binding
	NewLine key.Binding
	Editor  key.Binding
	Submit  key.Binding
}

TextKeyMap is the keybindings for text fields.

type Theme

type Theme struct {
	Form           lipgloss.Style
	Group          lipgloss.Style
	FieldSeparator lipgloss.Style
	Blurred        FieldStyles
	Focused        FieldStyles
	Help           help.Styles
}

Theme is a collection of styles for components of the form. Themes can be applied to a form using the WithTheme option.

func ThemeBase

func ThemeBase() *Theme

ThemeBase returns a new base theme with general styles to be inherited by other themes.

func ThemeBase16

func ThemeBase16() *Theme

ThemeBase16 returns a new theme based on the base16 color scheme.

func ThemeCatppuccin

func ThemeCatppuccin() *Theme

ThemeCatppuccin returns a new theme based on the Catppuccin color scheme.

func ThemeCharm

func ThemeCharm() *Theme

ThemeCharm returns a new theme based on the Charm color scheme.

func ThemeDracula

func ThemeDracula() *Theme

ThemeDracula returns a new theme based on the Dracula color scheme.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL