# xpl-dropdown

A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. 
A selection within a dropdown does not change the parent trigger.

***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://apollo.xplordocs.com/?path=/story/components-select--select).***

<!-- Auto Generated Below -->


## Properties

| Property                 | Attribute           | Description                                                                                                                            | Type                                                                                                                                                                 | Default          |
| ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `anchorToTrigger`        | `anchor-to-trigger` | whether to anchor the dropdown to the trigger element, requires triggerId to be set                                                    | `boolean`                                                                                                                                                            | `false`          |
| `closeOnSelect`          | `close-on-select`   | options that are listed                                                                                                                | `boolean`                                                                                                                                                            | `true`           |
| `flipFallbackPlacements` | --                  | When `anchorToTrigger` is true, additional placements to try when the default `placement` does not fit (passed to Floating UI `flip`). | `Placement[]`                                                                                                                                                        | `undefined`      |
| `isOpen`                 | `open`              | text to display as heading                                                                                                             | `boolean`                                                                                                                                                            | `false`          |
| `mode`                   | `mode`              | constant representing number of options that can be selected                                                                           | `"multi" \| "single"`                                                                                                                                                | `'single'`       |
| `options`                | --                  | options that are listed                                                                                                                | `Partial<DropdownOption & DropdownOptionGroup>[]`                                                                                                                    | `undefined`      |
| `placement`              | `placement`         | Floating UI placement when `anchorToTrigger` is true (e.g. `bottom-start`, `top-start`).                                               | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'bottom-start'` |
| `selectOnFocus`          | `select-on-focus`   | whether selection should be made when focusing on interactive element                                                                  | `boolean`                                                                                                                                                            | `false`          |
| `selectedValues`         | `selected-values`   | The currently selected value(s) in the dropdown.                                                                                       | `string \| string[]`                                                                                                                                                 | `undefined`      |
| `triggerId`              | `trigger-id`        | the id for the element that triggers the open state                                                                                    | `string`                                                                                                                                                             | `undefined`      |
| `update`                 | --                  | call back function invoked when a selection is made                                                                                    | `(e: any, { component }: { component: Dropdown; }) => void`                                                                                                          | `undefined`      |


## Events

| Event          | Description                                          | Type                   |
| -------------- | ---------------------------------------------------- | ---------------------- |
| `isOpenChange` | Emitted when the open state of the dropdown changes. | `CustomEvent<boolean>` |


## Methods

### `handleSelect(e: any, { component }: { component: XplDropdownOption; }) => Promise<void>`

called on dropdown option click and keydown events to update isSelected states

#### Parameters

| Name  | Type                                | Description |
| ----- | ----------------------------------- | ----------- |
| `e`   | `any`                               |             |
| `__1` | `{ component: XplDropdownOption; }` |             |

#### Returns

Type: `Promise<void>`




## Dependencies

### Used by

 - [xpl-input-phone](../xpl-input/xpl-input-phone)
 - [xpl-input-time](../xpl-input/xpl-input-time)
 - [xpl-select](../xpl-select)

### Depends on

- [xpl-dropdown-group](xpl-dropdown-group)
- [xpl-dropdown-option](xpl-dropdown-option)

### Graph
```mermaid
graph TD;
  xpl-dropdown --> xpl-dropdown-group
  xpl-dropdown --> xpl-dropdown-option
  xpl-dropdown-group --> xpl-dropdown-group
  xpl-dropdown-group --> xpl-dropdown-option
  xpl-dropdown-group --> xpl-dropdown-heading
  xpl-dropdown-option --> xpl-icon
  xpl-input-phone --> xpl-dropdown
  xpl-input-time --> xpl-dropdown
  xpl-select --> xpl-dropdown
  style xpl-dropdown fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*