# Dropdown

> Part of fluentui-svelte. Read the global guide first (setup, rules and pitfalls): https://fluentui-svelte.dev/docs/llms.md, also shipped as node_modules/fluentui-svelte/skills/fluentui-svelte/SKILL.md

The Dropdown lets users select one or more options from a list of `DropdownOption` children. Options can render rich content, such as a `Persona`, and the current selection is exposed through a bindable `value`.

## Usage

```svelte
<script>
	import { Dropdown, DropdownOption } from 'fluentui-svelte';
</script>

<Dropdown aria-label="Choose an option">
	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
</Dropdown>
```

## Examples

### Custom Option Content

Options can render any content, such as a `Persona`. Pass a `text` prop so the closed dropdown can still display the selection.

```svelte
<Dropdown aria-label="Choose an option">
	<DropdownOption value="John Doe" text="John Doe">
		<Persona
			name="John Doe"
			primaryText="Software Engineer"
			presence={{ status: 'available' }}
			avatarProps={{ color: 'colorful', idForColor: '' }}
		/>
	</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
	<DropdownOption value="C" text="Option C">Option C</DropdownOption>
</Dropdown>
```

### Multiple Selection

Set the `multiple` prop to allow selecting more than one option.

```svelte
<Dropdown multiple aria-label="Choose options">
	<DropdownOption value="A" text="Option A">Option A</DropdownOption>
	<DropdownOption value="B" text="Option B">Option B</DropdownOption>
	<DropdownOption value="C" text="Option C">Option C</DropdownOption>
</Dropdown>
```

HTML attributes, including class, id and ARIA attributes, apply to the control element. Bind ref to access that control. Use wrapperAttributes and wrapperRef for the outer container.

## Component Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownProps -->

| Name                                                 | Type                                              | Default              | Description                                                                                                          |
| ---------------------------------------------------- | ------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `shape`                                              | `'circular'` &#124; `'rounded'` &#124; `'square'` | `'rounded'`          | Shape of the input surface, including its border and focus indicator.                                                |
| `value` _bindable_                                   | `string` &#124; `string[]`                        | `multiple ? [] : ''` | The selected value. An array of values when `multiple` is set.                                                       |
| `multiple`                                           | `boolean`                                         |                      | Allows more than one option to be selected at a time.                                                                |
| `placeholder`                                        | `string`                                          | `'Select an option'` | The text shown by the trigger while no option is selected.                                                           |
| `disabled`                                           | `boolean`                                         |                      | Disables the user interaction.                                                                                       |
| `name`                                               | `string` &#124; `null`                            |                      | The name the value is submitted under. Without one, the form leaves the value out, as with any field.                |
| `wrapperRef` _bindable_                              | `HTMLDivElement` &#124; `null`                    |                      | The DOM reference of the wrapper element.                                                                            |
| `wrapperAttributes`                                  | `HTMLAttributes`                                  |                      | The attributes to spread on the wrapper element.                                                                     |
| `ref` _bindable_                                     | `HTMLSelectElement` &#124; `null`                 |                      | The DOM reference of the native select that holds the value. The other attributes of the dropdown are applied to it. |
| `buttonRef` _bindable_                               | `HTMLButtonElement` &#124; `null`                 |                      | The DOM reference of the button that opens the dropdown.                                                             |
| `buttonAttributes`                                   | `HTMLButtonAttributes`                            |                      | The attributes to spread on the button that opens the dropdown.                                                      |
| `flyoutRef` _bindable_                               | `HTMLDivElement` &#124; `null`                    |                      | The DOM reference of the flyout element.                                                                             |
| `flyoutProps`                                        | `FlyoutProps`                                     |                      | The props to spread on the flyout.                                                                                   |
| `flyoutMaxHeight`                                    | `string`                                          |                      | The maximum height of the flyout, as a CSS length.                                                                   |
| `listboxRef` _bindable_                              | `HTMLUListElement` &#124; `null`                  |                      | The DOM reference of the listbox element.                                                                            |
| `listboxProps`                                       | `ListViewProps`                                   |                      | The props to spread on the listbox rendered inside the flyout.                                                       |
| `children`                                           | `Snippet`                                         |                      | The `DropdownOption` elements of the list.                                                                           |
| `DropdownMultipleValue` &#124; `DropdownSingleValue` |                                                   |                      |                                                                                                                      |
| `NativeFieldAttributes<HTMLSelectAttributes>`        |                                                   |                      |                                                                                                                      |

<!-- /props:DropdownProps -->

## DropdownOption Props

<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
<!-- props:DropdownOptionProps -->

| Name                      | Type     | Default | Description                                                                                                                                                          |
| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`                    | `string` |         | The text shown by the dropdown once the option is selected. Falls back to the rendered children, which the server cannot read: pass it when rendering on the server. |
| `ListViewItemProps<'li'>` |          |         |                                                                                                                                                                      |

<!-- /props:DropdownOptionProps -->