# Listbox

Select one or more items from a list of options.

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

Create labelled groups for your items.

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

Select multiple items from the list.

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

```

## Disabled

Disable the entire 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.Label>Label</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>

```

## Disabled Item

Disable specific items in the list.

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

```

## Search

Add a search input to filter items.

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

Control the text direction of the 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} dir="rtl">
	<Listbox.Label>Label</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>

```

## 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?                 | -          | Snippet\<\[HTMLAttributes\<"div">]> \| undefined                                                                                                                                                                 | Render the element yourself                                                                                                                                                                                                                                                       |

### ListboxRootProviderProps

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

### ListboxRootContextProps

| Property | Default | Type                                           | Description |
| -------- | ------- | ---------------------------------------------- | ----------- |
| children | -       | Snippet\<\[() => ListboxApi\<PropTypes, any>]> | -           |

### ListboxLabelProps

| Property | Default | Type                                               | Description                 |
| -------- | ------- | -------------------------------------------------- | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"label">]> \| undefined | Render the element yourself |

### ListboxInputProps

| Property | Default | Type                                               | Description                 |
| -------- | ------- | -------------------------------------------------- | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"input">]> \| undefined | Render the element yourself |

### ListboxContentProps

| Property | Default | Type                                            | Description                 |
| -------- | ------- | ----------------------------------------------- | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"ul">]> \| undefined | Render the element yourself |

### ListboxItemGroupProps

| Property | Default | Type                                             | Description                 |
| -------- | ------- | ------------------------------------------------ | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"div">]> \| undefined | Render the element yourself |

### ListboxItemGroupLabelProps

| Property | Default | Type                                             | Description                 |
| -------- | ------- | ------------------------------------------------ | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"div">]> \| 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?          | -       | Snippet\<\[HTMLAttributes\<"li">]> \| undefined | Render the element yourself            |

### ListboxItemTextProps

| Property | Default | Type                                              | Description                 |
| -------- | ------- | ------------------------------------------------- | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"span">]> \| undefined | Render the element yourself |

### ListboxItemIndicatorProps

| Property | Default | Type                                              | Description                 |
| -------- | ------- | ------------------------------------------------- | --------------------------- |
| element? | -       | Snippet\<\[HTMLAttributes\<"span">]> \| undefined | Render the element yourself |