bubbles/list

Frequently Asked Questions

These are some of the most commonly asked questions regarding the list bubble.

Adding Custom Items

There are a few things you need to do to create custom items. First off, they need to implement the list.Item and list.DefaultItem interfaces.

// Item is an item that appears in the list.
type Item interface {
	// FilterValue is the value we use when filtering against this item when
	// we're filtering the list.
	FilterValue() string
}

// DefaultItem describes an items designed to work with DefaultDelegate.
type DefaultItem interface {
	Item
	Title() string
	Description() string
}

You can see a working example in our Kancli project built explicitly for a tutorial on lists and composite views in Bubble Tea.

VIDEO

Customizing Styles

Rendering (and behavior) for list items is done via the ItemDelegate interface. It can be a little confusing at first, but it allows the list to be very flexible and powerful.

If you just want to alter the default style you could do something like:

import "github.com/charmbracelet/bubbles/v2/list"

// Create a new default delegate
d := list.NewDefaultDelegate()

// Change colors
c := lipgloss.Color("#6f03fc")
d.Styles.SelectedTitle = d.Styles.SelectedTitle.Foreground(c).BorderLeftForeground(c)
d.Styles.SelectedDesc = d.Styles.SelectedTitle.Copy() // reuse the title style here

// Initailize the list model with our delegate
width, height := 80, 40
l := list.New(listItems, d, width, height)

// You can also change the delegate on the fly
l.SetDelegate(d)

This code would replace this line in the list-default example.

For full control over the way list items are rendered you can also define your own ItemDelegate too (example).