Finder

Key bindings (default mode)

Key	Action
Any character	Append to query
Backspace	Delete last query character
Ctrl+U	Clear query
↑ / Ctrl+P	Move selection up
↓ / Ctrl+N	Move selection down
Home	Jump to first result
End	Jump to last result
PgUp / PgDn	Page scroll
Tab	Toggle preview pane (if previewFunc is set)
Enter	Select highlighted item
Esc	Cancel (fires onCancel)

Vim mode

Enable with SetVimMode(true). In vim mode:

• Press / to enter search mode (typing goes to the query)
• Press Esc to leave search mode (keys become navigation)
• Navigation: j/k to move, gg/G for first/last

Preview pane

finder.SetPreviewFunc(func(item string) string {
    return fetchDetails(item)
})

When a previewFunc is set, Tab toggles a right-side preview showing the returned string for the currently highlighted item.

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

Finder is a fuzzy-search picker with live result filtering, optional grouped categories, preview pane, and vim mode. Type to filter; Enter selects; Tab toggles preview (when previewFunc is set); Esc cancels.

Constructor func NewFinder() *Finder

Usage

finder := components.NewFinder().
  SetPlaceholder("Search commands...").
  SetPrompt("> ").
  SetItems([]components.FinderItem{
    {ID: "deploy", Label: "Deploy", Description: "Ship to production", Category: "Actions"},
    {ID: "rollback", Label: "Rollback", Description: "Revert last deploy", Category: "Actions"},
  }).
  SetShowDescription(true).
  SetVimMode(false)
finder.SetPreview(func(item components.FinderItem) string {
  return "Preview of " + item.Label
})
finder.SetOnSelect(func(item components.FinderItem) {
  fmt.Println("ran:", item.ID)
})

fmt.Println(finder != nil)

Methods

Method	Signature	Description
AddRecent	func (f *Finder) AddRecent(id string) *Finder	AddRecent adds an item to recent list
Clear	func (f *Finder) Clear() *Finder	Clear resets the finder
ClearRecent	func (f *Finder) ClearRecent() *Finder	ClearRecent clears recent items
GetFiltered	func (f *Finder) GetFiltered() []FinderItem	GetFiltered returns all items matching current query
GetQuery	func (f *Finder) GetQuery() string	GetQuery returns current search text
GetSelected	func (f *Finder) GetSelected() *FinderItem	GetSelected returns currently highlighted item
SetCaseSensitive	func (f *Finder) SetCaseSensitive(sensitive bool) *Finder	SetCaseSensitive enables case-sensitive matching
SetCategories	func (f *Finder) SetCategories(categories []FinderCategory) *Finder	SetCategories defines category ordering
SetItems	func (f *Finder) SetItems(items []FinderItem) *Finder	SetItems sets the searchable items
SetMaxVisible	func (f *Finder) SetMaxVisible(max int) *Finder	SetMaxVisible limits visible results
SetMinScore	func (f *Finder) SetMinScore(score int) *Finder	SetMinScore sets minimum fuzzy match score
SetOnCancel	func (f *Finder) SetOnCancel(fn func()) *Finder	SetOnCancel is called when Esc is pressed
SetOnChange	func (f *Finder) SetOnChange(fn func(item FinderItem)) *Finder	SetOnChange is called when selection changes
SetOnQueryChange	func (f *Finder) SetOnQueryChange(fn func(query string)) *Finder	SetOnQueryChange is called when search text changes
SetOnSelect	func (f *Finder) SetOnSelect(fn func(item FinderItem)) *Finder	SetOnSelect is called when Enter is pressed on an item
SetPlaceholder	func (f *Finder) SetPlaceholder(text string) *Finder	SetPlaceholder sets input placeholder text
SetPreview	func (f *Finder) SetPreview(fn PreviewFunc) *Finder	SetPreview enables preview pane
SetPreviewRatio	func (f *Finder) SetPreviewRatio(ratio float64) *Finder	SetPreviewRatio sets preview pane width ratio
SetPrompt	func (f *Finder) SetPrompt(prompt string) *Finder	SetPrompt sets the input prompt
SetQuery	func (f *Finder) SetQuery(query string) *Finder	SetQuery sets search text programmatically
SetRecentItems	func (f *Finder) SetRecentItems(ids []string) *Finder	SetRecentItems sets recently used items
SetShowCategories	func (f *Finder) SetShowCategories(show bool) *Finder	SetShowCategories enables category headers
SetShowDescription	func (f *Finder) SetShowDescription(show bool) *Finder	SetShowDescription enables description column
SetShowIcons	func (f *Finder) SetShowIcons(show bool) *Finder	SetShowIcons enables item icons
SetVimMode	func (f *Finder) SetVimMode(enabled bool) *Finder	SetVimMode enables vim-style navigation (j/k to move, / to search, Esc exits search). When disabled (default), all typing goes directly to the search query.

Types

type FinderCategory struct FinderCategory defines a named group header shown above its items. Lower Priority values appear first in the grouped list.

Field	Type	Description
Name	string
Icon	string
Priority	int	Lower = shown first

type FinderItem struct FinderItem is a single entry in the Finder list. Label and Description are both searched; Keywords add extra match terms without appearing in the UI. Matches is populated by the filter pass to drive character-level highlight.

Field	Type	Description
ID	string	Unique identifier
Label	string	Primary display text (searchable)
Description	string	Secondary text (searchable)
Category	string	Group/category name
Icon	string	Optional icon
Keywords	[]string	Additional search terms
Data	any	User data
Score	int	Match score (set by filtering)
Matches	[]int	Character indices that matched (for highlighting)

type PreviewFunc PreviewFunc generates preview content for an item