list

README

List

Vertical selectable list with cursor highlight, optional hints, disabled items, and internal scrolling.

Install

glyph add list

This copies list.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 list library to keep in sync.

Hello, world

package main

import (
	"fmt"

	"github.com/truffle-dev/glyph/components/list"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	l := list.New(theme.Default).
		WithHeight(8).
		WithItems([]list.Item{
			{Label: "Inbox", Hint: "12 unread"},
			{Label: "Drafts"},
		})
	fmt.Println(l.View())
}

API surface

Package: list

Types

• Item
• List

Functions and methods

• New
• WithItems
• WithHeight
• WithWidth
• WithCursor
• Update
• View
• Selected
• Cursor

Dependencies

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

Notes

Build items with []list.Item{{Label, Hint, Disabled, Value}}. Up/down or k/j walk; Home/g and End/G jump. Read Selected() to drive the detail panel your parent model renders.

See also

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

License

MIT, same as the rest of glyph.

Documentation

Overview

Package list renders a vertical list of items with a single selected cursor. It's the navigation primitive most agent UIs reach for after tabs: a sidebar of conversations, a queue of jobs, a result set, a settings index.

A list owns the cursor and the visible window; it does not own the items' detail view. The parent reads Selected() and renders the detail panel itself.

Index

• type Item
• type List
  • func New(t theme.Theme) List
  • func (l List) Cursor() int
  • func (l List) Selected() (Item, int, bool)
  • func (l List) Update(msg tea.Msg) (List, tea.Cmd)
  • func (l List) View() string
  • func (l List) WithCursor(glyph string) List
  • func (l List) WithHeight(h int) List
  • func (l List) WithItems(items []Item) List
  • func (l List) WithWidth(w int) List

Types

type Item

type Item struct {
	// Label is the visible text.
	Label string
	// Hint is optional secondary text rendered after the label in a muted color.
	Hint string
	// Disabled rows render dimmed and can't be selected.
	Disabled bool
	// Value is opaque payload the parent can pull off Selected().
	Value any
}

Item is one row in the list.

type List

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

List is a vertical selectable list.

func New

func New(t theme.Theme) List

New constructs an empty List with theme-aware styling.

func (List) Cursor

func (l List) Cursor() int

Cursor returns the current cursor index.

func (List) Selected

func (l List) Selected() (Item, int, bool)

Selected returns the currently highlighted item along with its index. The bool is false on an empty list.

func (List) Update

func (l List) Update(msg tea.Msg) (List, tea.Cmd)

Update handles cursor movement keys. Up/down arrows and j/k step by one; Home/g goes to the first enabled item, End/G to the last.

func (List) View

func (l List) View() string

View renders the list, including only the window of items visible at this scroll offset.

func (List) WithCursor

func (l List) WithCursor(glyph string) List

WithCursor sets the cursor glyph. Default is ›.

func (List) WithHeight

func (l List) WithHeight(h int) List

WithHeight sets the maximum visible rows. The list scrolls internally when items exceed the height. Minimum 1.

func (List) WithItems

func (l List) WithItems(items []Item) List

WithItems replaces the item set. Resets the cursor to the first enabled item if the previous cursor falls out of range.

func (List) WithWidth

func (l List) WithWidth(w int) List

WithWidth clamps the render width. Values <= 0 mean natural width.