Logo

Midnight Owl UI

Autocomplete

Stable v1.0.2

A text input that suggests matches as you type. Works with local arrays or async data sources, and lets you choose what gets displayed versus what gets stored.

Interactive Playground

Experiment with Autocomplete states, sizing, and popover behaviors.

Configuration
Top
Behavior
Small (sm)
Appearance
None
320px (Default)
States
v-model Output:
""
Live Source Code
<Autocomplete
  v-model="searchQuery"
  :options="vehicleOptions"
  id="vehicle-search-autocomplete"
  label="Search Vehicles"
  placeholder="Type a model name..."
/>

Real-World Usage Examples

Explore custom templates, async API fetching, and dynamic creation workflows.

1. Object Resolution & Custom Slots

Uses optionLabel="name" to bind object keys automatically, and injects the `#option` template for rich dropdown content. 

<Autocomplete
  v-model="selectedPort"
  :options="portOptions"
  optionLabel="name"
  label="Search Port Terminals"
  placeholder="e.g., Manila, Cebu"
  openOnFocus
>
  <template #option="{ option }">
    <div class="flex w-full flex-col">
      <span class="font-bold text-main">{{ option.name }}</span>
      <span class="text-[10px] text-muted">
        Code: {{ option.code }} | Cap: {{ option.capacity }}
      </span>
    </div>
  </template>
</Autocomplete>

2. Asynchronous API Fetching

Turns off internal filtering (:filter="false") and triggers an 800ms debounce on the @search event to simulate backend calls. 

<Autocomplete
  v-model="query"
  :options="asyncOptions"
  :filter="false"
  :loading="isSearching"
  label="Vehicle Order Number (VOF)"
  placeholder="Type 'TR-100'..."
  @search="handleAsyncSearch"
/>
Current Database Array:Admin, Dispatcher, Driver

3. Dynamic "Create New" Routing

Typing a role that doesn't exist exposes the `#action` slot. Clicking the green 'Add' button fires @create-new, appending the value to the array and selecting it. 

<Autocomplete
  v-model="role"
  :options="roleOptions"
  label="Assign Personnel Role"
  placeholder="Type role name..."
  openOnFocus
  @create-new="handleAddNew"
/>

API Reference

Props

Name
Type / Signature
Default
Description
v-model
string
""
The input text value bound to the component.
id
string
undefined
Overrides the auto-generated id applied to the underlying input element and its label.
options
any[]
[]
Array of data objects or strings to suggest.
label
string
undefined
Top or left-aligned input label.
labelPosition
"top" | "left"
"top"
Alignment of the label relative to the input field.
placeholder
string
""
Text shown when the input is empty.
size
"xs" | "sm" | "md" | "lg" | "xl"
"sm"
Dimensional size of the component.
filter
boolean
true
If true, performs internal client-side array filtering. Set to false if handling filtering externally (e.g. API).
openOnFocus
boolean
false
If true, opens the popover immediately upon input focus regardless of text length.
debounce
number
300
Milliseconds to wait after the last keystroke before firing the @search event. Set to 0 to emit on every keystroke.
optionLabel
string | function
"label"
Key or function to resolve the label from object options.
optionValue
string | function
"value"
Key or function to resolve the value from object options.
iconStart
string
undefined
Icon to display on the left side of the input.
iconEnd
string
undefined
Icon to display on the right side of the input.
maxHeight
string | number
320
Maximum height of the dropdown popover (in pixels).
required
boolean
false
Marks the field as required and renders an asterisk next to the label.
disabled
boolean
false
Disables user interaction and grays out the component.
loading
boolean
false
Replaces trailing icon with a spinning loader.
error
string | boolean | string[]
false
Applies red error styling and displays error message(s) below the input.

Events

Event Name
Payload Signature
Description
@select
(option: any)
Fired when a user clicks an option or presses Enter on an active item.
@search
(value: string)
Fired instantly on keystroke. Ideal for triggering async backend queries.
@create-new
(value: string)
Fired when the "Add" button is clicked in the empty state.
@focus
(event: FocusEvent)
Fired when the input receives focus.
@blur
(event: FocusEvent)
Fired when the input loses focus.
@open
()
Fired when the suggestions popover is opened.
@close
()
Fired when the suggestions popover is closed.

Slots

Slot Name
Exposed Bindings
Description
option
{ option: any, index: number, active: boolean }
Custom template for each row in the suggestion list.
empty
-
Custom template when the search yields no results.
action
-
Custom action area below the empty state (contains "Create New" by default).