Autocomplete     

The Quasar Autocomplete component binds to the parent textfield (eg. QInput, QSearch, QChipsInput) and offers suggestions to the user, while the user is typing. The suggestions offered to the user are based on either a static list of results or on an asynchronous function call (eg. containing an Ajax request).

Installation

Edit /quasar.conf.js:

framework: {
  components: ['QAutocomplete']
}

Basic Usage

As long as this component is rendered by Vue, it will capture all Ajax calls.

<!-- Binds to parent QInput -->
<q-input color="amber" v-model="terms" placeholder="Type 'fre'">
  <q-autocomplete
    @search="search"
    :min-characters="3"
    @selected="selected"
  />
</q-input>

<!-- Binds to parent QSearch -->
<q-search v-model="terms" placeholder="Start typing a country name">
  <q-autocomplete @search="search" @selected="selected" />
</q-search>

<!-- Adds a separator between results -->
<q-search v-model="terms">
  <q-autocomplete
    separator
    @search="search"
    @selected="selected"
  />
</q-search>

<!-- Binds to parent QChipsInput -->
<q-chips-input v-model="terms" placeholder="Start typing a country name">
  <q-autocomplete @search="search" @selected="selected" />
</q-chips-input>

Vue Properties

Vue PropertyTypeDefault ValueDescription
min-charactersNumber1How many minimum characters can trigger component to suggest something?
max-resultsNumber6How many results can we display at a time?
max-heightStringNone(v0.17+) CSS unit to determine the maximum height of Autocomplete popover.
static-dataObjectNoneUse static suggestions. No need to do an Ajax call. Filtering is provided by Autocomplete component.
filterFunctionInternal implementationIf provided, autocomplete will perform custom filtering.
debounceNumber500Time in milliseconds, between key presses and finding new results. Good for delay, if using AJAX requests.
separatorBooleanfalseIf set to true, it ads a delimeter between the values to select from.
value-fieldString/Functionvalue(v0.17+) What property should we use for filling out the model with? Check example in the next sections.

Vue Methods

No need to trigger these methods manually as they are invoked automatically. Only use them when your use-case is something very specific.

Vue MethodDescription
trigger()Trigger suggestions (parent textfield must be focused).
hide()Hide suggestions Popover.
setValue()Set textfield string to the value supplied.

Vue Events

Vue EventDescription
@search(terms, Function done)Triggered by the component when a search should start and offer some results.
@selected(item, keyboard)Triggered when user has selected a suggestion. On keyboard navigation the event is emitted with a second parameter set to true (v0.17+).
@showTriggered when the selections popup opens.
@hideTriggered when selections popup closes.

Example for search event:

function search (terms, done) {
  // do something with terms, like an Ajax call for example
  // then call done(Array results)

  // DO NOT forget to call done! When no results or an error occured,
  // just call with empty array as param. Example: done([])
}

Using value-field

<!-- as a String -->
<q-autocomplete
  @search="search"
  @selected="selected"
  :min-characters="0"
  value-field="icon"
/>

<!-- as a Function -->
<q-autocomplete
  @search="search"
  @selected="selected"
  :value-field="v => `${ v.icon } - ${ v.label }`"
/>

Using Static Data

When using static data, specify an Object (notice that it uses some properties from List and List Items components:

// static-data
{
  // Property name that will be used by filter() to filter the array of objects below.
  field: 'value',

  list: [
    {
      value: 'Romania', // The value given, when selected
      label: 'Romania', // The value displayed as main label for this suggested selection

      sublabel: 'Continent: Europe', // optional
      icon: 'location_city', // optional
      stamp: '18 mil', // optional
      ...
    },
    ...
  ]
}

Here is the full list of properties that can be used:

PropertyTypeDescription
leftColorStringColor for left side from Quasar Color Palette.
iconStringIcon on the left to use.
avatarStringURL pointing to statics for an avatar.
letterStringOne character String.
leftInvertedBooleanInvert mode, but only for icon and letter.
leftTextColorStringOverride default “white” text-color when using an icon or letter only.
imageStringURL pointing to statics for an image.
labelStringMain label of the selection.
sublabelStringSub-label of the selection.
labelLinesString/NumberNumber of lines that label can expand to.
sublabelLinesString/NumberNumber of lines that the sublabel can expand to.
insetBooleanInset Label if no left-side is specified (no icon, avatar, letter or image).
rightColorStringColor for right side from Quasar Color Palette.
rightIconStringIcon on the right to use.
rightAvatarStringURL pointing to statics for an avatar on right side.
rightLetterStringOne character String for right side.
rightImageStringURL pointing to statics for an image on right side.
rightInvertedBooleanInvert mode, but only for icon and letter.
rightTextColorStringOverride default “white” text-color when using an icon or letter only.
stampStringStamp to use for right side. Example: ‘10 min ago’.
<template>
  <q-search inverted color="secondary" v-model="terms" placeholder="Featuring static data">
    <q-autocomplete
      :static-data="{field: 'value', list: countries}"
      @selected="selected"
    />
  </q-search>
</template>

<script>
import countries from 'countries.json'

// See above for the data format for the array of objects with required and optional data
export default {
  data () {
    return {
      terms: '',
      countries
    }
  }
}
</script>

Custom Filter

To perform custom filtering like fuzzy search, provide an optional function with following signature:

<template>
  <q-search v-model="terms">
    <!-- Provide custom filter function -->
    <q-autocomplete
      :filter="myFilter"
      @search="search"
      @selected="selected"
    />
  </q-search>
</template>

<script>
// fuzzysearch (needle, haystack) { return true|false }

export default {
  ...,
  methods: {
    myFilter(terms, { field, list }) {
      const token = terms.toLowerCase();
      return list.filter(item => fuzzysearch(token, item[field].toLowerCase()));
    }
  }
}
</script>

Using Asynchronous Method (Ajax call?)

If you’d like to call up data from the server, you may also do so with the following usage of search() method.

<template>
  <q-search v-model="terms" placeholder="Start typing a country name">
    <q-autocomplete @search="search" @selected="selected" />
  </q-search>
</template>

<script>
export default {
  ...
  methods: {
    search (terms, done) {
      // make an AJAX call
      // then call done(Array results)

      // DO NOT forget to call done! When no results or an error occurred,
      // just call with empty array as param. Example: done([])
    }
  },
  ...
}
</script>
Color Picker Editor - WYSIWYG
Last updated: Sat May 25 2019
Caught a mistake or want to contribute to the documentation? Suggest an edit on GitHub