ListBox

A list selection component supporting single and multiple selection modes.

Basic

Custom rendered items with avatars, names, emails, and check icons.

Selectable roles with icon badges, descriptions, and a disabled option.

Prop	Type	Default	Description
`items`	`{ value: string; label: string }[]`	—	Array of selectable items.
`value`	`string \| string[]`	—	The selected value(s) (controlled).
`defaultValue`	`string \| string[]`	—	The initial selected value(s) (uncontrolled).
`onValueChange`	`(value: string \| string[]) => void`	—	Called when the selection changes.
`multiple`	`boolean`	`false`	Allows multiple items to be selected.
`color`	`"blue" \| "red" \| "green" \| "yellow" \| "purple" \| "neutral" \| string`	`"blue"`	Accent color for selected items.
`renderItem`	`(item: ListBoxItem, selected: boolean) => ReactNode`	—	Custom render function for each item. Receives the item data and selection state.
`--mantle-bg`	`CSS variable`	`theme default`	Override the background color via style. e.g. style={{ "--mantle-bg": "#1a1a2e" }}
`--mantle-border`	`CSS variable`	`theme default`	Override the border color via style. Set to "transparent" to remove. e.g. style={{ "--mantle-border": "#e94560" }}
`--mantle-text`	`CSS variable`	`theme default`	Override the text color via style. e.g. style={{ "--mantle-text": "#ffffff" }}
`--mantle-ring`	`CSS variable`	`accent`	Override the focus ring color via style. e.g. style={{ "--mantle-ring": "#e94560" }}
`--mantle-option-hover`	`CSS variable`	`gradient`	Override the option hover background via style. e.g. style={{ "--mantle-option-hover": "#3b82f6" }}

items

{ value: string; label: string }[]

Array of selectable items.

value

string | string[]

The selected value(s) (controlled).

defaultValue

string | string[]

The initial selected value(s) (uncontrolled).

onValueChange

(value: string | string[]) => void

Called when the selection changes.

multiplefalse

boolean

Allows multiple items to be selected.

color"blue"

Accent color for selected items.

renderItem

(item: ListBoxItem, selected: boolean) => ReactNode

Custom render function for each item. Receives the item data and selection state.

--mantle-bgtheme default

CSS variable

Override the background color via style. e.g. style={{ "--mantle-bg": "#1a1a2e" }}

--mantle-bordertheme default

CSS variable

Override the border color via style. Set to "transparent" to remove. e.g. style={{ "--mantle-border": "#e94560" }}

--mantle-texttheme default

CSS variable

Override the text color via style. e.g. style={{ "--mantle-text": "#ffffff" }}

--mantle-ringaccent

CSS variable

Override the focus ring color via style. e.g. style={{ "--mantle-ring": "#e94560" }}

--mantle-option-hovergradient

CSS variable

Override the option hover background via style. e.g. style={{ "--mantle-option-hover": "#3b82f6" }}