# Listbox

Accessible listbox for single and multi selection.

```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>
	);
}

```

## 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>
	);
}

```

## 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>
	);
}

```

## 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>
	);
}

```

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>
	);
}

```

## Search

Utilize the `Input` component to implement simple search.

```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("");

	// oxlint-disable-next-line react/preserve-manual-memoization
	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>
	);
}

```

## Direction

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

```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>
	);
}

```

## 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>
	);
}
```

## API Reference

### Root

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

### Provider

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

### Context

| Prop     | Description | Type                                                | Default |
| -------- | ----------- | --------------------------------------------------- | ------- |
| children | -           | (listbox: ListboxApi\<PropTypes, any>) => ReactNode | -       |

### Label

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

### Input

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

### Content

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

### ItemGroup

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

### ItemGroupLabel

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

### Item

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

### ItemText

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

### ItemIndicator

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