Listbox · Skeleton

Select a food

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function Default() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection}>
			<Listbox.Label>Select a food</Listbox.Label>
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

Select a food

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});
</script>

<Listbox class="w-full max-w-md" {collection}>
	<Listbox.Label>Select a food</Listbox.Label>
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Groups

Organize items into categorized groups.

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple', type: 'Fruits' },
	{ label: 'Banana', value: 'banana', type: 'Fruits' },
	{ label: 'Orange', value: 'orange', type: 'Fruits' },
	{ label: 'Carrot', value: 'carrot', type: 'Vegetables' },
	{ label: 'Broccoli', value: 'broccoli', type: 'Vegetables' },
	{ label: 'Spinach', value: 'spinach', type: 'Vegetables' },
];

export default function Group() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
		groupBy: (item) => item.type,
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection}>
			<Listbox.Content>
				{collection.group().map(([type, items]) => (
					<Listbox.ItemGroup key={type}>
						<Listbox.ItemGroupLabel>{type}</Listbox.ItemGroupLabel>
						{items.map((item) => (
							<Listbox.Item key={item.value} item={item}>
								<Listbox.ItemText>{item.label}</Listbox.ItemText>
								<Listbox.ItemIndicator />
							</Listbox.Item>
						))}
					</Listbox.ItemGroup>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple', type: 'Fruits' },
		{ label: 'Banana', value: 'banana', type: 'Fruits' },
		{ label: 'Orange', value: 'orange', type: 'Fruits' },
		{ label: 'Carrot', value: 'carrot', type: 'Vegetables' },
		{ label: 'Broccoli', value: 'broccoli', type: 'Vegetables' },
		{ label: 'Spinach', value: 'spinach', type: 'Vegetables' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
		groupBy: (item) => item.type,
	});
</script>

<Listbox class="w-full max-w-md" {collection}>
	<Listbox.Content>
		{#each collection.group() as [type, items] (type)}
			<Listbox.ItemGroup>
				<Listbox.ItemGroupLabel>{type}</Listbox.ItemGroupLabel>
				{#each items as item (item.value)}
					<Listbox.Item {item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				{/each}
			</Listbox.ItemGroup>
		{/each}
	</Listbox.Content>
</Listbox>

Multiple

Set the multiple proper to allow selecting more than one item.

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function Multiple() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection} selectionMode="multiple">
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});
</script>

<Listbox class="w-full max-w-md" {collection} selectionMode="multiple">
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Disabled

Set the disabled prop to enable the disabled state.

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function Disabled() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection} disabled={true}>
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});
</script>

<Listbox class="w-full max-w-md" {collection} disabled={true}>
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Which can also be enabled per item.

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function DisabledItem() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
		isItemDisabled: (item) => item.value === 'banana',
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection}>
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
		isItemDisabled: (item) => item.value === 'banana',
	});
</script>

<Listbox class="w-full max-w-md" {collection}>
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Search

Utilize the Input component to implement simple search.

Search for Food

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';
import { useMemo, useState } from 'react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function Search() {
	const [query, setQuery] = useState('');

	const collection = useMemo(() => {
		const items = data.filter((item) => item.label.toLowerCase().includes(query.toLowerCase()));
		return useListCollection({ items });
	}, [query]);

	return (
		<Listbox className="w-full max-w-md" collection={collection}>
			<Listbox.Label>Search for Food</Listbox.Label>
			<Listbox.Input placeholder="Type to search..." value={query} onInput={(e) => setQuery(e.currentTarget.value)} />
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

Search for Food

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	let query = $state('');

	const collection = $derived(
		useListCollection({
			items: data.filter((item) => item.label.toLowerCase().includes(query.toLowerCase())),
			itemToString: (item) => item.label,
			itemToValue: (item) => item.value,
		}),
	);
</script>

<Listbox class="w-full max-w-md" {collection}>
	<Listbox.Label>Search for Food</Listbox.Label>
	<Listbox.Input placeholder="Type to search..." value={query} oninput={(e) => (query = e.currentTarget.value)} />
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Direction

Set the text direction ( ltr or rtl ) using the dir prop.

Select a food

tsx

import { Listbox, useListCollection } from '@skeletonlabs/skeleton-react';

const data = [
	{ label: 'Apple', value: 'apple' },
	{ label: 'Banana', value: 'banana' },
	{ label: 'Orange', value: 'orange' },
	{ label: 'Carrot', value: 'carrot' },
	{ label: 'Broccoli', value: 'broccoli' },
	{ label: 'Spinach', value: 'spinach' },
];

export default function Dir() {
	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});

	return (
		<Listbox className="w-full max-w-md" collection={collection} dir="rtl">
			<Listbox.Label>Select a food</Listbox.Label>
			<Listbox.Content>
				{collection.items.map((item) => (
					<Listbox.Item key={item.value} item={item}>
						<Listbox.ItemText>{item.label}</Listbox.ItemText>
						<Listbox.ItemIndicator />
					</Listbox.Item>
				))}
			</Listbox.Content>
		</Listbox>
	);
}

Select a food

svelte

<script lang="ts">
	import { Listbox, useListCollection } from '@skeletonlabs/skeleton-svelte';

	const data = [
		{ label: 'Apple', value: 'apple' },
		{ label: 'Banana', value: 'banana' },
		{ label: 'Orange', value: 'orange' },
		{ label: 'Carrot', value: 'carrot' },
		{ label: 'Broccoli', value: 'broccoli' },
		{ label: 'Spinach', value: 'spinach' },
	];

	const collection = useListCollection({
		items: data,
		itemToString: (item) => item.label,
		itemToValue: (item) => item.value,
	});
</script>

<Listbox class="w-full max-w-md" {collection} dir="rtl">
	<Listbox.Label>Select a food</Listbox.Label>
	<Listbox.Content>
		{#each collection.items as item (item.value)}
			<Listbox.Item {item}>
				<Listbox.ItemText>{item.label}</Listbox.ItemText>
				<Listbox.ItemIndicator />
			</Listbox.Item>
		{/each}
	</Listbox.Content>
</Listbox>

Anatomy

Here’s an overview of how the Listbox component is structured in code:

tsx

import { Listbox } from '@skeletonlabs/skeleton-react';

export default function Anatomy() {
	return (
		<Listbox>
			<Listbox.Label />
			<Listbox.Content>
				<Listbox.Item>
					<Listbox.ItemText />
					<Listbox.ItemIndicator />
				</Listbox.Item>
			</Listbox.Content>
		</Listbox>
	);
}

svelte

<script lang="ts">
	import { Listbox } from '@skeletonlabs/skeleton-svelte';
</script>

<Listbox>
	<Listbox.Label />
	<Listbox.Content>
		<Listbox.Item>
			<Listbox.ItemText />
			<Listbox.ItemIndicator />
		</Listbox.Item>
	</Listbox.Content>
</Listbox>

API Reference

Root

Prop	Default	Type
`orientation`	"vertical"	"horizontal" \| "vertical" \| undefined The orientation of the listbox.
`collection`	—	ListCollection<any> \| GridCollection<any> The item collection
`ids`	—	Partial<{ root: string; content: string; label: string; item: (id: string \| number) => string; itemGroup: (id: string \| number) => string; itemGroupLabel: (id: string \| number) => string; }> \| undefined The ids of the elements in the listbox. Useful for composition.
`disabled`	—	boolean \| undefined Whether the listbox is disabled
`disallowSelectAll`	—	boolean \| undefined Whether to disallow selecting all items when `meta+a` is pressed
`onHighlightChange`	—	((details: HighlightChangeDetails<any>) => void) \| undefined The callback fired when the highlighted item changes.
`onValueChange`	—	((details: ValueChangeDetails<any>) => void) \| undefined The callback fired when the selected item changes.
`value`	—	string[] \| undefined The controlled keys of the selected items
`defaultValue`	[]	string[] \| undefined The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox.
`highlightedValue`	—	string \| null \| undefined The controlled key of the highlighted item
`defaultHighlightedValue`	—	string \| null \| undefined The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox.
`loopFocus`	false	boolean \| undefined Whether to loop the keyboard navigation through the options
`selectionMode`	"single"	SelectionMode \| undefined How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys.
`scrollToIndexFn`	—	((details: ScrollToIndexDetails) => void) \| undefined Function to scroll to a specific index
`selectOnHighlight`	—	boolean \| undefined Whether to select the item when it is highlighted
`deselectable`	—	boolean \| undefined Whether to disallow empty selection
`typeahead`	—	boolean \| undefined Whether to enable typeahead on the listbox
`onSelect`	—	((details: SelectionDetails) => void) \| undefined Function called when an item is selected
`dir`	"ltr"	"ltr" \| "rtl" \| undefined The document's text/writing direction.
`getRootNode`	—	(() => ShadowRoot \| Node \| Document) \| undefined A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
`element`	—	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

Provider

Prop	Default	Type
`value`	—	ListboxApi<PropTypes, any>
`element`	—	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

Context

Prop	Default	Type
`children`	—	(listbox: ListboxApi<PropTypes, any>) => ReactNode

Label

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"label">) => Element) \| undefined Render the element yourself

Input

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"input">) => Element) \| undefined Render the element yourself

Content

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"ul">) => Element) \| undefined Render the element yourself

ItemGroup

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

ItemGroupLabel

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

Item

Prop	Default	Type
`item`	—	any The item to render
`highlightOnHover`	—	boolean \| undefined Whether to highlight the item on hover
`element`	—	((attributes: HTMLAttributes<"li">) => Element) \| undefined Render the element yourself

ItemText

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"span">) => Element) \| undefined Render the element yourself

ItemIndicator

Prop	Default	Type
`element`	—	((attributes: HTMLAttributes<"span">) => Element) \| undefined Render the element yourself

Root

Prop	Default	Type
`orientation`	"vertical"	"horizontal" \| "vertical" \| undefined The orientation of the listbox.
`collection`	—	ListCollection<any> \| GridCollection<any> The item collection
`ids`	—	Partial<{ root: string; content: string; label: string; item: (id: string \| number) => string; itemGroup: (id: string \| number) => string; itemGroupLabel: (id: string \| number) => string; }> \| undefined The ids of the elements in the listbox. Useful for composition.
`disabled`	—	boolean \| undefined Whether the listbox is disabled
`disallowSelectAll`	—	boolean \| undefined Whether to disallow selecting all items when `meta+a` is pressed
`onHighlightChange`	—	((details: HighlightChangeDetails<any>) => void) \| undefined The callback fired when the highlighted item changes.
`onValueChange`	—	((details: ValueChangeDetails<any>) => void) \| undefined The callback fired when the selected item changes.
`value`	—	string[] \| undefined The controlled keys of the selected items
`defaultValue`	[]	string[] \| undefined The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox.
`highlightedValue`	—	string \| null \| undefined The controlled key of the highlighted item
`defaultHighlightedValue`	—	string \| null \| undefined The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox.
`loopFocus`	false	boolean \| undefined Whether to loop the keyboard navigation through the options
`selectionMode`	"single"	SelectionMode \| undefined How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys.
`scrollToIndexFn`	—	((details: ScrollToIndexDetails) => void) \| undefined Function to scroll to a specific index
`selectOnHighlight`	—	boolean \| undefined Whether to select the item when it is highlighted
`deselectable`	—	boolean \| undefined Whether to disallow empty selection
`typeahead`	—	boolean \| undefined Whether to enable typeahead on the listbox
`onSelect`	—	((details: SelectionDetails) => void) \| undefined Function called when an item is selected
`dir`	"ltr"	"ltr" \| "rtl" \| undefined The document's text/writing direction.
`getRootNode`	—	(() => ShadowRoot \| Node \| Document) \| undefined A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
`element`	—	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Provider

Prop	Default	Type
`value`	—	() => ListboxApi<PropTypes, any>
`element`	—	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Context

Prop	Default	Type
`children`	—	Snippet<[() => ListboxApi<PropTypes, any>]>

Label

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"label">]> \| undefined Render the element yourself

Input

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"input">]> \| undefined Render the element yourself

Content

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"ul">]> \| undefined Render the element yourself

ItemGroup

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

ItemGroupLabel

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Item

Prop	Default	Type
`item`	—	any The item to render
`highlightOnHover`	—	boolean \| undefined Whether to highlight the item on hover
`element`	—	Snippet<[HTMLAttributes<"li">]> \| undefined Render the element yourself

ItemText

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"span">]> \| undefined Render the element yourself

ItemIndicator

Prop	Default	Type
`element`	—	Snippet<[HTMLAttributes<"span">]> \| undefined Render the element yourself