Ui3nAutocomplete

Autocomplete component with search, multi-select, chips, and custom filtering capabilities.

Props

Name	Type	Default	Description
name	string | undefined	—	HTML name attribute for form submission
chips	boolean | undefined	—	Whether to show chips
clearOnSelect	boolean | undefined	false	Whether to clear input on select
customFilter	((value: T, query: string) => boolean) | undefined	—	Custom filter function
disabled	boolean | undefined	—	Whether autocomplete is disabled
itemDisabled	((item: T) => boolean) | undefined	—	Whether an individual item cannot be picked. A disabled item is still listed, greyed out and inert to both the pointer and the keyboard. Use it when leaving the item out would be worse than showing it: an absence explains nothing, while a disabled row - with a reason rendered through the `item` slot - does. A predicate rather than a flag on the item itself, so that a caller can answer from state of its own without copying or mutating its data.
filterKeys	string[] | undefined	[]	Filter keys
hideSelected	boolean | undefined	false	Whether to hide selected items
lockScroll	boolean | undefined	false	Whether to lock scroll when menu is open
items*	T[]	[]	Items to display
itemTitle	keyof T | undefined	"name"	Property to use as title
itemValue	keyof T | undefined	"id"	Property to use as value
modelValue*	T[] | T[keyof T][]	—	Current autocomplete value
addNewValue	boolean | undefined	false	Whether to allow adding new values
newValueValidator	((value: string) => boolean) | undefined	—	New value validator function
multiple	boolean | undefined	—	Whether to allow multiple selection
noDataText	string | undefined	—	Text to show when no data
placeholder	string | undefined	—	Placeholder text
returnObject	boolean | undefined	—	Whether to return the whole object or just the value

Events

Event Name	Arguments / Value Type	Description
update:modelValue	T[] | T[keyof T][]	Emitted when model value updates
update:search	string	Emitted when search value updates
update:focused	boolean	Emitted when focused state updates
valid:new-value	boolean	Emitted when new value validation status updates

Slots

Slot Name	Scope Props (v-slot)	Description
#item	{ item: T; index: number; query?: string | undefined; }	Item slot
#chip	{ item: T | T[keyof T]; index: number; isHighlighted: boolean; }	Chip slot
#noDataText	—	No data text slot
#selection	{ value: T[] | T[keyof T][]; }	Selection slot

CSS Variables

Set any of these where you need it — on :root, on a container, or on the element itself through [data-ui3n] — and the component follows. Leave them alone and it uses the defaults below.

Name	Default
--ui3n-autocomplete-border-radius	4px
--ui3n-autocomplete-font-size	12px
--ui3n-autocomplete-item-font-size	13px
--ui3n-autocomplete-min-height	32px
--ui3n-autocomplete-padding-block	4px
--ui3n-autocomplete-padding-inline	8px

Usage Examples

Basic single select

Basic single select

Simple autocomplete with single item selection

Selected: - none -

Multiple selection

Multiple selection

Select multiple items from the list

Selected: []

Chips mode

Chips mode

Display selected items as removable chips

Selected: []

Custom filter

Custom filter

Use custom filter function to search by multiple fields (name and email)

Selected: []

Custom item slot

Custom item slot

Customize dropdown item rendering using the item slot

Selected: []

Return object mode

Return object mode

Return the whole object instead of just the value

Selected objects:

[]

Add new value

Add new value

Allow adding new values with validation. Type a new tag and press Enter, Tab, or leave the field

Tags: none

Type a new tag (2-20 chars) and press Enter, Tab, or leave the field to add it

Disabled state

Disabled state

Autocomplete in disabled mode

Disabled items

Disabled items

Keep an item in the list but make it unpickable. Use it when leaving the item out would explain less than showing it greyed out: pass a reason through the item slot. Disabled items are skipped by the arrow keys and by Enter as well as by the pointer

Selected: none

Disabled items stay in the list, and answer neither the pointer nor the arrow keys

Hide selected and no data text

Hide selected and no data text

Hide already selected items from dropdown and show custom text when no items available

Selected: none

Selected items are hidden from the dropdown

Remote async search

Remote async search

Listen to search updates to fetch items from a remote server dynamically with loading status

Selected User IDs: none

Data is loaded dynamically from mock API on every keystroke with 500ms delay.

Preselected initial values

Preselected initial values

Demonstrates how the component automatically parses and renders pre-populated model values for both primitive IDs and objects

Case A: Flat IDs Mode (default)

ts

node

Current ref value: [ "ts", "node" ]

Case B: Return Object Mode

Vue.js

Current ref value:

[
  {
    "id": "vue",
    "name": "Vue.js",
    "level": "Expert"
  }
]