@empathyco/x-components
Version:
Empathy X Components
80 lines (60 loc) • 4.25 kB
Markdown
---
title: BaseDropdown
---
# BaseDropdown
Dropdown component that mimics a Select element behavior, but with the option
to customize the toggle button and each item contents.
## Props
| Name | Description | Type | Default |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------ |
| <code>items</code> | List of items to display. | <code>DropdownItem[]</code> | <code></code> |
| <code>modelValue</code> | The selected item. | <code>DropdownItem \| null</code> | <code></code> |
| <code>ariaLabel</code> | Description of what the dropdown is used for. | <code>string</code> | <code></code> |
| <code>animation</code> | Animation component to use for expanding the dropdown. This is a single element animation,<br />so only `<transition>` components are allowed. | <code>AnimationProp</code> | <code>() => NoAnimation</code> |
| <code>searchTimeoutMs</code> | Time to wait without receiving any keystroke before resetting the items search query. | <code>number</code> | <code>1000</code> |
## Events
| Event name | Properties | Description |
| ----------------- | ---------- | ----------- |
| update:modelValue | |
## Slots
| Name | Description | Bindings<br />(name - type - description) |
| ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <code>toggle</code> | Used to render the contents of the dropdown toggle button. If not provided, it uses | <br />**item** <code>string | number | Identifiable</code> - The item data to render. |
| <code>item</code> | Used to render the contents of the dropdown toggle button. If not provided, it uses | <br /><br />**item** <code>string | number | Identifiable</code> - Item to render |
## Example
The `Dropdown` component is a simple yet customizable select component. The component needs to work
the list of items available to select, which are passed using the `items` prop, and the selected
item, which is passed in using the `value` prop.
The supported items must be an array that can contain unique strings, unique numbers, or objects
with a unique `id` property.
The content of each item can be customized using the `item` slot, which apart from the data of the
item, it also receives via prop if the element is selected or highlighted.
There `toggle` slot can be used to customize the button that opens the dropdown. If this is not
provided, the `item` slot will be used for that.
```vue
<template>
<BaseDropdown v-model="value" :items="items">
<template #toggle="{ item, isOpen }">{{ item }} {{ isOpen ? '🔼' : '🔽' }}️</template>
<template #item="{ item, isSelected, isHighlighted }">
<span v-if="isHighlighted">🟢</span>
<span v-if="isSelected">✅</span>
<span>{{ item }}</span>
</template>
</BaseDropdown>
</template>
<script>
import { BaseDropdown } from '@empathyco/x-components'
export default {
name: 'DropdownTest',
components: {
BaseDropdown,
},
data() {
return {
items: ['a', 2, { id: '3' }],
value: 'a',
}
},
}
</script>
```