commandpalette

README

Command Palette

Filterable modal command picker.

Install

glyph add command-palette

This copies command-palette.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no command-palette library to keep in sync.

Hello, world

package main

import (
	"fmt"

	commandpalette "github.com/truffle-dev/glyph/components/command-palette"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	p := commandpalette.New(theme.Default).
		WithCommands([]commandpalette.Command{
			{ID: "save", Title: "Save file", Keybinding: "ctrl+s"},
			{ID: "open", Title: "Open file", Keybinding: "ctrl+o"},
		}).
		WithSize(72, 14)
	fmt.Println(p.View())
}

API surface

Package: commandpalette

Types

• Command
• SelectMsg
• CancelMsg
• Matcher
• Palette

Functions and methods

• New
• WithCommands
• WithFilter
• WithSize
• WithTitle
• WithPlaceholder
• WithMatcher
• Filter
• Cursor
• Init
• Update
• View
• SubstringMatcher

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0

Notes

Emits commandpalette.SelectMsg on Enter with the chosen Command, commandpalette.CancelMsg on Esc. Pass WithCommands to load the list. Substitute the substring matcher with WithMatcher for fuzzy ranking.

See also

• examples/showcase — single-binary TUI composing the seven main surfaces
• components/command-palette/story — runnable story binary (go run -tags glyph_story ./components/command-palette/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package commandpalette renders a fuzzy-filtered command picker as a modal surface. Consumers supply a list of commands, render the View, route key events through Update, and observe SelectMsg / CancelMsg.

The default matcher is case-insensitive substring on Title (and on Group when present). Replace the matcher by setting a function via WithMatcher — the function returns a non-zero score to keep a command, zero to drop. Higher scores rank earlier.

Index

• func SubstringMatcher(cmd Command, query string) int
• type CancelMsg
• type Command
• type Matcher
• type Palette
  • func New(t theme.Theme) Palette
  • func (p Palette) Cursor() int
  • func (p Palette) Filter() string
  • func (p Palette) Init() tea.Cmd
  • func (p Palette) Update(msg tea.Msg) (Palette, tea.Cmd)
  • func (p Palette) View() string
  • func (p Palette) WithCommands(cmds []Command) Palette
  • func (p Palette) WithFilter(s string) Palette
  • func (p Palette) WithMatcher(m Matcher) Palette
  • func (p Palette) WithPlaceholder(s string) Palette
  • func (p Palette) WithSize(w, h int) Palette
  • func (p Palette) WithTitle(s string) Palette
• type SelectMsg

Functions

func SubstringMatcher

func SubstringMatcher(cmd Command, query string) int

SubstringMatcher is the default matcher. Case-insensitive substring match on Title and Group. Returns 100 when query is empty (every command passes), or the inverse position of the match (higher = earlier in the string).

Types

type CancelMsg

type CancelMsg struct{}

CancelMsg is emitted when the user presses Esc.

type Command

type Command struct {
	ID          string // stable identifier returned in SelectMsg
	Title       string // primary label rendered on the row
	Description string // optional secondary label rendered under Title
	Group       string // optional grouping label rendered as a section header
	Keybinding  string // optional shortcut hint rendered right-aligned
}

Command is one row the user can select.

type Matcher

type Matcher func(cmd Command, query string) int

Matcher returns a score for cmd against query. Zero score drops cmd from the result list. Higher scores sort earlier. The default matcher does a case-insensitive substring match on Title and Group.

type Palette

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

Palette is a Bubble Tea model for a filterable command picker.

func New

func New(t theme.Theme) Palette

New constructs a Palette with the default substring matcher. No commands are loaded; call WithCommands.

func (Palette) Cursor

func (p Palette) Cursor() int

Cursor returns the index into the filtered list, not into the source list.

func (Palette) Filter

func (p Palette) Filter() string

Filter returns the current filter text.

func (Palette) Init

func (p Palette) Init() tea.Cmd

Init implements tea.Model.

func (Palette) Update

func (p Palette) Update(msg tea.Msg) (Palette, tea.Cmd)

Update handles key events: filter typing, arrow navigation, Enter, Esc.

func (Palette) View

func (p Palette) View() string

View renders the palette as a bordered card.

func (Palette) WithCommands

func (p Palette) WithCommands(cmds []Command) Palette

WithCommands sets the command list. Cursor resets to 0.

func (Palette) WithFilter

func (p Palette) WithFilter(s string) Palette

WithFilter presets the filter text.

func (Palette) WithMatcher

func (p Palette) WithMatcher(m Matcher) Palette

WithMatcher replaces the scoring function. Pass nil to restore the default.

func (Palette) WithPlaceholder

func (p Palette) WithPlaceholder(s string) Palette

WithPlaceholder sets the filter input placeholder.

func (Palette) WithSize

func (p Palette) WithSize(w, h int) Palette

WithSize sets the rendered width and visible-row height.

func (Palette) WithTitle

func (p Palette) WithTitle(s string) Palette

WithTitle sets the title rendered above the filter input.

type SelectMsg

type SelectMsg struct {
	Command Command
}

SelectMsg is emitted when the user presses Enter on a non-empty match list.