A dropdown input for choosing one value from a list of options. Supports field mapping to adapt to any data shape, grouped options, filterable search, and fully customizable option rendering via snippets.
Basic Example
Pass an array of objects with text and optionally icon fields. Bind value to track the selected value. Set disabled: true on any item to make
it unselectable.
Field Mapping
Your data rarely matches the component's default field names (text, value). Use the fields prop to remap without transforming your data.
Grouped Options
Items with a children array are rendered as labelled option groups with a visual divider
between groups. Only leaf items (children) are selectable — group headers are presentational.
Filterable
Enable the filterable prop to add a search input at the top of the dropdown. Useful
for long option lists. The filter matches against the display text of each option. Use filterPlaceholder to customize the search input hint.
Custom Option Rendering
Use the itemContent snippet to fully control what appears inside each dropdown
option. The snippet receives a ProxyItem — use proxy.label, proxy.icon, and proxy.get('fieldName') to access any field.
Props
- items: Array of objects or grouped option arrays
- fields: Remap your data keys to component fields
- value (bindable): Currently selected value
- selected (bindable): Currently selected raw item object
- placeholder: Text shown when nothing is selected
- size: Size variant (
sm,md,lg) - align: Dropdown alignment (
start,end) - direction: Dropdown direction (
down,up) - disabled: Disable the entire select
- filterable: Show a search input in the dropdown
- filterPlaceholder: Placeholder for the filter input
- class: Additional CSS classes on the root element
Snippets
- itemContent(proxy): Custom rendering for dropdown options
- groupContent(proxy): Custom rendering for group headers
- [name](proxy): Per-item snippet — set
item.snippet = 'name'
ProxyItem API
Snippets receive a ProxyItem instance:
- proxy.label: Mapped display text
- proxy.icon: Mapped icon class
- proxy.value: The extracted value field (primitive)
- proxy.disabled: Whether the item is disabled
- proxy.get('field'): Read any field by mapped or raw name
Events
- onchange(value, item): Fired when selection changes — receives the extracted value and the raw item object