# Listbox

Select one or more items from a list of options.

```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>Label</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

Create labelled groups for your items.

```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.Label>Label</Listbox.Label>
			<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

Select multiple items from the list.

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

```

## Disabled

Disable the entire listbox.

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

```

## Disabled Item

Disable specific items in the list.

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

```

## Search

Add a search input to filter items.

```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>Label</Listbox.Label>
			<Listbox.Input placeholder="Type to search..." value={query} onChange={(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

Control the text direction of the listbox.

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

```

## API Reference

### ListboxRootProps

| Property                 | Default    | Type                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                       |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.&#xA;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.&#xA;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.&#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. |
| 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                                                                                                                                                                                                                                                       |

### ListboxRootProviderProps

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

### ListboxRootContextProps

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

### ListboxLabelProps

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

### ListboxInputProps

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

### ListboxContentProps

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

### ListboxItemGroupProps

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

### ListboxItemGroupLabelProps

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

### ListboxItemProps

| Property          | Default | Type                                                          | Description                            |
| ----------------- | ------- | ------------------------------------------------------------- | -------------------------------------- |
| 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            |

### ListboxItemTextProps

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

### ListboxItemIndicatorProps

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