List provides support for showing and updating a selection list in given buffer. It displays a list of options with one option highlighted - the selected item. The List component provides native support for optional filtering the items as it’s built around the concept of a ‘matcher’, which provides matching items given a search string.

See also:


List (matcher, opts={})

Creates a new List.

It is also possible to request that particular segments of an item are highlighted for a particular item as it’s displayed, by defining a .item_highlights table on the item itself (see the Item highlights section at the end of this section).

The matcher is called on initialization and whenever the update() function is called. The search_text argument provided in update() is passed to the matcher and the displayed items are replaced with the new list of items returned from the matcher.

Item highlights

Certain segments of an item can be highlighted as they are displayed, if a item_highlights table is specified for the item. Such a table should have one sub table for each list column for which highlights should be applied, containing one or more highlighting specifications indicating the start and end position of the highlight, relative to the item column.

Start positions can be specified by using one of the below:



A table specifying a header and styles for each column. The schema of this table is identical to the columns argument in the StyledText.for_table function. Read/write.


A table containing the items currently displayed. Read-only.


The maximum number of total rows occupied by the list. This includes any header and status rows. Should the size be small enough that not all items can be shown the list will show a sub set of items along with a pagination indicator at the bottom. Read/write.


The minimum number of total rows occupied by the list. If the number of items aren’t sufficient to fill up the number of rows, filler text is displayed on each line to fill the extra space. Read/write.


The index of the first item currently shown. Always 1 unless the list is constrained by max_rows.


The number of items currently shown. Always equal to the number of items unless the list is constrained by max_rows.


The number of rows used by the list in the buffer.


The currently selected item. Read/write.


draw ()

“Draws” the list into the associated buffer, i.e. inserts or updates the list in the buffer.

insert (buffer)

Associates the list with the specified buffer. Any subsequent calls to draw or update will cause the list to be drawn into the given buffer.

next_page ()

Displays the next page of the list’s item.

on_refresh (listener)

Adds a listener to the list. The listener will be invoked every time the list is redrawn in the associated buffer, and will be passed the list as the sole argument.

prev_page ()

Displays the previous page of the list’s item.

select_next ()

Selects the next item in the list. Causes the list to scroll if neccessary.

select_prev ()

Selects the previous item in the list. Causes the list to scroll if neccessary.

update (search_text, preserve_position = false)

Updates the list of displayed items to the items returned by calling matcher(search_text). See matcher in the constructor above.

If preserve_position is true, the current position in the list is maintained if possible.