Select

Key bindings

Key	Action
Space	Toggle dropdown open/close
↑ / k	Move selection up (requires dropdown open)
↓ / j	Move selection down (requires dropdown open)
Esc	Close dropdown without confirming

Note: Enter is intentionally reserved for form-level submission. Close and confirm with Space or by navigating away.

Options

Use SetOptions when label and value are the same string, or SetOptionsWithValues when you need separate display and storage values:

// Label == Value
sel.SetOptions([]string{"Alpha", "Beta", "Gamma"})

// Distinct label and value
sel.SetOptionsWithValues([]components.SelectOption{
    {Label: "North America", Value: "na"},
    {Label: "Europe",        Value: "eu"},
})

SetDefault selects by value string; SetSelected selects by index. SetSelectedIndex returns an error for out-of-range indices.

Form integration

Select implements FormField and binds automatically when registered with a Form. The bound value is the selected option’s Value string.

catppuccin-frappecatppuccin-lattecatppuccin-macchiatocatppuccin-mochadraculadracula-lighteverforest-darkeverforest-lightgithub-darkgithub-lightgruvbox-darkgruvbox-lightkanagawamonokainordonedarkonelightrosepinerosepine-dawnrosepine-moonsolarized-darksolarized-lighttokyonight-daytokyonight-moontokyonight-nighttokyonight-storm

Select is a dropdown selection component. It implements IndexedValueProvider[string].

Constructor func NewSelect(name string) *Select

Usage

ExampleSelect is a kitchen-sink walkthrough of the Select API: distinct display labels and stored values, a default selection, a change handler, reading the current selection, and selecting programmatically by value.

sel := components.NewSelect("region").
  SetLabel("Region").
  SetPlaceholder("Choose a region").
  SetOptionsWithValues([]components.SelectOption{
    {Label: "North America", Value: "na"},
    {Label: "Europe", Value: "eu"},
    {Label: "Asia Pacific", Value: "apac"},
  }).
  SetDefault("eu")

sel.SetOnChange(func(e *components.ChangeEvent[components.SelectOption]) {
  fmt.Printf("changed to %s (%s)\n", e.NewValue.Label, e.NewValue.Value)
})

fmt.Println("value:", sel.Value())
fmt.Println("label:", sel.SelectedOption().Label)

_ = sel.SetSelectedValue("apac")
fmt.Println("value:", sel.Value())

Methods

Method	Signature	Description
Clear	func (s *Select) Clear()	Clear resets the selection to none.
ClearField	func (s *Select) ClearField()	ClearField resets the selection. Implements FormField.
FieldValue	func (s *Select) FieldValue() any	FieldValue returns the selected option value as an any. Implements FormField.
GetFieldHeight	func (s *Select) GetFieldHeight() int	GetFieldHeight returns the preferred height for this field.
GetName	func (s *Select) GetName() string	GetName returns the field name.
GetValue	func (s *Select) GetValue() string	GetValue returns the selected value.
HasValue	func (s *Select) HasValue() bool	HasValue returns true if an option is selected.
SelectedIndex	func (s *Select) SelectedIndex() int	SelectedIndex returns the selected index (-1 if none).
SelectedOption	func (s *Select) SelectedOption() SelectOption	SelectedOption returns the selected option.
SetDefault	func (s *Select) SetDefault(value string) *Select	SetDefault sets the default selected option by value.
SetExpanded	func (s *Select) SetExpanded(expanded bool) *Select	SetExpanded sets whether the dropdown is open.
SetFieldValue	func (s *Select) SetFieldValue(value any) error	SetFieldValue sets the select's value from an any. Accepts a string (matched against option values) or an int (option index). Implements FormField.
SetLabel	func (s *Select) SetLabel(label string) *Select	SetLabel sets the field label.
SetOnChange	func (s *Select) SetOnChange(handler ChangeHandler[SelectOption]) *Select	SetOnChange sets the change handler (new API).
SetOptions	func (s *Select) SetOptions(options []string) *Select	SetOptions sets available options where Label and Value are identical. Use SetOptionsWithValues when the display text should differ from the stored value.
SetOptionsWithValues	func (s *Select) SetOptionsWithValues(options []SelectOption) *Select	SetOptionsWithValues sets options with distinct display labels and stored values.
SetPlaceholder	func (s *Select) SetPlaceholder(placeholder string) *Select	SetPlaceholder sets the placeholder text.
SetSelected	func (s *Select) SetSelected(index int) *Select	SetSelected sets the selected index.
SetSelectedIndex	func (s *Select) SetSelectedIndex(index int) error	SetSelectedIndex sets the selected index, returning an error if out of range.
SetSelectedValue	func (s *Select) SetSelectedValue(value string) error	SetSelectedValue sets the selected option by value.
Value	func (s *Select) Value() string	Value returns the selected value. This method is part of the ValueProvider interface.

Types

type ChangeHandler ChangeHandler handles value changes

type SelectOption struct SelectOption represents an option in a select dropdown.

Field	Type	Description
Label	string
Value	string