Listbox#

Listbox is tkinter’s list of selectable text lines (tk.Listbox), themed by ttkbootstrap. Lines are addressed by integer index (0-based) or the special index "end" / "active". This page is the complete reference for its own options and methods; the shared widget methods are under Capabilities.

Options#

Option	Type	Description
`autostyle`	`bool`	Constructor only. `True` (default) paints the listbox with the active theme and repaints on a theme switch; `False` opts out.
`listvariable`	`Variable`	A `StringVar` holding the list items as a Tcl list — keeps the widget and the variable in sync.
`selectmode`	`str`	`"browse"` (single, default), `"single"`, `"multiple"`, or `"extended"` (click-drag / Shift / Ctrl ranges).
`selectbackground`	`str`	The background color of selected lines.
`selectforeground`	`str`	The text color of selected lines.
`selectborderwidth`	`int`	The border width of selected lines, in pixels.
`activestyle`	`str`	How the active line is marked: `"underline"`, `"dotbox"`, or `"none"`.
`exportselection`	`bool`	Whether the selection is exported to the X selection / clipboard.
`font`	`str \| Font`	The font for the lines.
`foreground` (`fg`)	`str`	The text color.
`background` (`bg`)	`str`	The surface color.
`disabledforeground`	`str`	The text color when `state` is `"disabled"`.
`justify`	`str`	Line alignment: `"left"`, `"center"`, or `"right"`.
`width`	`int`	The requested width in characters (`0` fits the content).
`height`	`int`	The requested height in lines (`0` fits the content).
`borderwidth` (`bd`)	`int`	The 3-D border width in pixels.
`relief`	`str`	The border style: `"flat"`, `"raised"`, `"sunken"`, `"groove"`, `"ridge"`, or `"solid"`.
`highlightthickness`	`int`	The width of the focus highlight around the widget.
`highlightcolor`	`str`	The focus-highlight color when the widget has focus.
`highlightbackground`	`str`	The focus-highlight color when the widget does not have focus.
`state`	`str`	`"normal"` or `"disabled"`.
`cursor`	`str`	The mouse cursor (see Cursors).
`takefocus`	`bool`	Whether the listbox accepts keyboard focus during traversal.
`setgrid`	`bool`	Whether the window resizes in whole lines/characters.
`xscrollcommand`	`callable`	A callback connecting the listbox to a horizontal scrollbar.
`yscrollcommand`	`callable`	A callback connecting the listbox to a vertical scrollbar.

Methods#

Content#

insert(index, *elements)

Insert one or more lines before index.

Parameters:

index – the position, or "end" to append.
elements – the strings to add.

Returns:

None.

delete(first, last=None)

Delete the lines from first through last (or a single line).

Returns:: None.

get(first, last=None)

Return the text of a line, or a tuple of lines over a range.

Returns:: one line’s text, or a tuple for a range.
Return type:: str | tuple[str, …]

size()

Return the number of lines.

Return type:: int

Indices#

index(index)

Resolve an index expression to an integer line number.

Return type:: int

nearest(y)

Return the index of the visible line nearest a y pixel coordinate.

Return type:: int

see(index)

Scroll so the line at index is visible.

Returns:: None.

activate(index)

Make the line at index the active one (the keyboard-navigation cursor).

Returns:: None.

Selection#

curselection()

Return the indices of the currently selected lines.

Return type:: tuple[int, …]

selection_set(first, last=None)

Select a line, or a range of lines. Alias: select_set.

Returns:: None.

selection_clear(first, last=None)

Deselect a line or range. Alias: select_clear.

Returns:: None.

selection_includes(index)

Report whether the line at index is selected. Alias: select_includes.

Return type:: bool

selection_anchor(index)

Set the selection anchor — the fixed end of a range selection. Alias: select_anchor.

Returns:: None.

Per-line appearance#

itemconfigure(index, **options)

Set (or query) the appearance of one line. Alias: itemconfig.

Parameters:: options – background, foreground, selectbackground, selectforeground.
Returns:: the option spec when queried with a single option name, else None.

itemcget(index, option): Return one per-line option.

Scrolling#

yview(*args)

Query or set the vertical view; usually wired to a scrollbar via yscrollcommand. xview is the horizontal counterpart, and both have *_moveto(fraction) and *_scroll(number, what) variants.

Returns:: with no args, the visible fraction (first, last); else None.
Return type:: tuple | None

scan_mark(x, y)

Record a starting point for a fast drag-scroll.

Returns:: None.

scan_dragto(x, y)

Scroll the view relative to the scan_mark point.

Returns:: None.

Shared capabilities#

Listbox also has the methods every widget inherits — configuration, placement, event binding, lifecycle, focus, and introspection. These are documented under Capabilities.