vue-simple-suggest

Simple yet feature-rich autocomplete component for Vue.js

Install

npm install --save vue-simple-suggest

See installation guide for more options.

Table of contents

• vue-simple-suggest
  • Install
  • Table of contents
  • What is it
    • Features
    • New features?
  • Examples:
    • Simple example
    • Async example
  • Installation
    • NPM
    • Unpkg
    • Importing
      • Polyfills
    • Usage
  • Build Setup
  • Default Controls
  • Component API
    • TLDR
    • CSS class structure
      • Transitions
    • API definitions
      • Props
        • mode
      • Emitted Events
      • Ref Methods
      • Ref Event Handlers
      • Ref Data
    • Slots
      • Custom input
      • Accessibility on custom input
      • Custom suggestion item
      • Custom miscellaneous item slots
  • Contributors

What is it

This is a simple yet feature-rich suggestion/autocomplete component for Vue.js.

Actually, it's so feature rich, that it's possible to do crazy stuff with it, like

• Imitating drop-downs and drop-down menus
• Turn suggestions list into an actual suggestions table
• Work with ANY type of custom input passed (like type=button, radio and etc.)
• ... And many more things

And, as a bonus, it is very light.

Features

• v-model support.
• Automatic accessibility attributes (WAI-ARIA complete)
• Switching v-model type (select/input).
• Custom input element through default slot.
• Custom list items through named scoped slots.
• All HTML5-valid props for default input element are provided (type, tabindex and etc...).
• Customizable keyboard controls.
• Rich and simple API.
• CSS classes for quick and easy restyling.
• Many build variants to choose from.
• Flexible and customizable component design.
• Optional polyfills for IE importable from the lib.

All of the props, events and slots are OPTIONAL for this component, so it can be used without any configuration at all.

New features?

If you feel that something important is missing (or found a bug) - feel free to create an issue. :)

Examples:

To use the component just install via NPM:

npm install --save vue-simple-suggest

Then, in your Vue.js component/page do the following...

Simple example

If you need to suggest things from a static array:

<!-- Some component.vue -->
<template>
  <vue-simple-suggest
    v-model="chosen"
    :list="simpleSuggestionList"
    :filter-by-query="true">
<!-- Filter by input text to only show the matching results -->
  </vue-simple-suggest>

  <br>

  <p>Chosen element: {{ chosen }}</p>
</template>

<script>
  import VueSimpleSuggest from 'vue-simple-suggest'
  import 'vue-simple-suggest/dist/styles.css' // Optional CSS

  export default {
    components: {
      VueSimpleSuggest
    },
    data() {
      return {
        chosen: ''
      }
    },
    methods: {
      simpleSuggestionList() {
        return [
          'Vue.js',
          'React.js',
          'Angular.js'
        ]
      }
    }
  }
</script>

Async example

If you're dealing with async data from server (example using https://swapi.co/):

<!-- Some component.vue -->
<template>
  <vue-simple-suggest
    v-model="chosen"
    display-attribute="name"
    value-attribute="url"
    :list="getSuggestionList"
  ></vue-simple-suggest>

  <br>

  <p>Chosen element: {{ chosen }}</p>
</template>

<script>
  import VueSimpleSuggest from 'vue-simple-suggest'
  import 'vue-simple-suggest/dist/styles.css' // Optional CSS

  export default {
    components: {
      VueSimpleSuggest
    },
    data() {
      return {
        chosen: ''
      }
    },
    methods: {
      // Function returning a promise as a factory for suggestion lists.
      //
      // vue-simple-suggest calls it automatically when an update to the list is needed,
      // no need for watchers here!
      getSuggestionList() {
        return fetch('https://swapi.co/api/people', { method: 'GET' })
          .then(response => response.json())
          .then(json => json.results); /*
          returns a promise with a list of star-wars characters
        */
      }
    }
  }
</script>

For a more advanced example (using wikipedia search) see our example source.

Installation

NPM

npm install --save vue-simple-suggest
# or
yarn add vue-simple-suggest

Unpkg

If including via this method - the component will automatically install itself.

<!-- UMD Component, async/await polyfills through promises -->
<script type="text/javascript" src="https://unpkg.com/vue-simple-suggest"></script>
<script type="text/javascript" src="https://unpkg.com/vue-simple-suggest@1.5.1"></script>
                                                              <!-- Specific version -->

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/vue-simple-suggest/dist/styles.css">

<!-- If you need polyfills, use IIFE verision below -->
<!-- IIFE build includes ALL polyfills: Object.assign, Promises, Generators, Async/Await! -->
<script type="text/javascript" src="https://unpkg.com/vue-simple-suggest/dist/iife.js"></script>

Importing

/// ESNext (original code, no pollyfills, single-file .vue component, css included)
import VueSimpleSuggest from 'vue-simple-suggest/lib'
///

/// ES6 (async polyfills)
import VueSimpleSuggest from 'vue-simple-suggest'
// or, if you have problems importing:
import VueSimpleSuggest from 'vue-simple-suggest/dist/es6'
///

/// ES7 and above (no polyfills)
import VueSimpleSuggest from 'vue-simple-suggest/dist/es7'
///

/// CommonJS (async, arrow-functions and promises are polyfilled)
const VueSimpleSuggest = require('vue-simple-suggest')
// or, if you have problems importing:
const VueSimpleSuggest = require('vue-simple-suggest/dist/cjs')
///

// Optional - import css separately with css loaders:
import 'vue-simple-suggest/dist/styles.css'

Polyfills

New in v1.8.3

vue-simple-suggest comes with minimal optional polyfills for IE11+ - Object.assign, Element.prototype.closest and Element.prototype.matches. You can import them like this:

import 'vue-simple-suggest/lib/polyfills';
// or
require('vue-simple-suggest/lib/polyfills');

Usage

Globaly:

// You don't need to do it, if including via <script> (umd, iife)
Vue.component('vue-simple-suggest', VueSimpleSuggest)

In single-file .vue components:

<script>
  import VueSimpleSuggest from 'vue-simple-suggest'
  import 'vue-simple-suggest/dist/styles.css' // Using a css-loader

  export default {
    components: {
      VueSimpleSuggest
    }
  }
</script>

Build Setup

# clone the repo
git clone https://github.com/KazanExpress/vue-simple-suggest.git
cd ./vue-simple-suggest

# install dependencies
npm install

# serve example with hot reload at localhost
npm run dev

# build example & readme for static serving
npm run docs

Default Controls

New in v1.2.0

These are default keyboard shortcuts.

Can be customized with the controls prop. All fields in this controls object are optional.

Default scheme:

JS object:

{
  selectionUp: [38],
  selectionDown: [40],
  select: [13],
  showList: [40],
  hideList: [27],
  autocomplete: [32, 13]
}

Component API

TLDR

<!-- Ref to access the API, v-model for efficient query binding -->
<vue-simple-suggest ref="vueSimpleSuggest" v-model="model"
  value-attribute="id"
  display-attribute="title"
  mode="input"
  placeholder="placeholder!!!"
  :list="getListFunction"
  :max-suggestions="10"
  :min-length="3"
  :debounce="100"
  :destyled="false"
  :remove-list="false"
  :filter-by-query="false"
  :filter="customFilterFunction"
  :value="defaultValue"
  :nullable-select="true"
  :controls="{
    selectionUp: [38, 33],
    selectionDown: [40, 34],
    select: [13, 36],
    showList: [40],
    hideList: [27, 35],
    autocomplete: [32, 13],
  }"
  @input="onInputEvent"
  @select="onSuggestSelect"
  @hover="onSuggestHover"
  @focus="onFocus"
  @blur="onBlur"
  @request-start="onRequestStart"
  @request-done="onRequestDone"
  @request-failed="onRequestFailed"
  @show-list="onShowList"
  @hide-list="onHideList"
>
  <!-- v-model on input itself is useless -->
  <input class="optional-custom-input">

  <!-- Appears o top of the list -->
  <template slot="misc-item-above" slot-scope="{ suggestions, query }">
    <div class="misc-item">
      <span>You're searching for {{ query }}.</span>
    </div>
    <div class="misc-item">
      <span>{{ suggestions.length }} suggestions are shown...</span>
    </div>
    <hr>
  </template>

  <div slot="suggestion-item" slot-scope="{ suggestion }" class="custom">{{ suggestion.title }}</div>

  <!-- Appears below the list -->
  <div class="misc-item" slot="misc-item-below" slot-scope="{ suggestions }" v-if="loading">
    <span>Loading...</span>
  </div>
</vue-simple-suggest>

CSS class structure

If there's a need to customize the appearance of the component, here's the internal class-structure:

// .designed is applied only if `destyled` prop is false.
.vue-simple-suggest.designed.focus // .focus is applied whenever the component is focused.
  .input-wrapper
    .default-input // Replaced with your custom input if default slot is provided.
  .suggestions // Also has transition classes, see below.
    .suggest-item

If you wish to use your existing classes, or frameworks like Bootstrap you can inject your own classes using the 'styles' prop:

<!-- Some component.vue -->
<template>
  <vue-simple-suggest
    v-model="chosen"
    :list="simpleSuggestionList"
    :styles="autoCompleteStyle"
    :destyled=true
    :filter-by-query="true">
  </vue-simple-suggest>
</template>

<script>
  ...
  export default {
    ...
    data() {
      return {
        autoCompleteStyle : {
          vueSimpleSuggest: "position-relative",
          inputWrapper: "",
          defaultInput : "form-control",
          suggestions: "position-absolute list-group z-1000",
          suggestItem: "list-group-item"
        }
      }
    },
    ...
  }
</script>`

<style lang="scss">
.z-1000 {
  z-index: 1000;
}
.hover {
  background-color: #007bff;
  color: #fff;
}
</style>

Scheme:

Transitions

New in v1.8.0

You can also define custom list transitions by defining css rules for the transition named vue-simple-suggest on the .suggestions div:

.suggestions {
  /* It's improtant to have a cpecific pivot point for transition:*/
  opacity: 1;
}

.vue-simple-suggest-enter-active.suggestions,
.vue-simple-suggest-leave-active.suggestions {
  /* Transition length here:*/
  transition: opacity .2s;
}

.vue-simple-suggest-enter.suggestions,
.vue-simple-suggest-leave-to.suggestions {
  /* Transition rule for "disengaged" element:*/
  opacity: 0;
}

API definitions

Props

mode

New in v1.4.0

Determines the event, that triggers v-model. Can be one of 'input' (default) or 'select'.

For example, if 'input' is chosen - then v-model will update the value each time an input event is fired, setting the input's string.

Same is for 'select' - v-model changes only when something is selected from the list, setting the selected value (string, object or whatever) to its argument.

A proper use-case for it being when one wants to use the component only for selection binding and custom input for text binding:

<vue-simple-suggest v-model="selected" mode="select">
  <input v-model="text">
</vue-simple-suggest>

Emitted Events

Ref Methods

accessed via $refs.*your ref name here*

Ref Event Handlers

accessed via $refs.*your ref name here*

You can use these to imitate some of the component's behaviours.

Ref Data

accessed via $refs.*your ref name here*

Slots

Custom input

default slot (optional)

Supports nesting. Input props can be passed to a custom input to avoid their processing by vue-simple-suggest. Defaults to a simple input with props passed to vue-simple-suggest.

Warning: v-model on a custom input IS NOT the same as v-model on vue-simple-suggest!

<!--  Default HTMLInputElement example:  -->
<vue-simple-suggest v-model="model" placeholder="Text here" type="search" pattern="[a-z]+"/>

<!--  Vanilla HTMLInputElement example 1:  -->
<vue-simple-suggest>
  <input pattern="[a-z]+">
</vue-simple-suggest>

<!--  Vanilla HTMLInputElement example 2:  -->
<vue-simple-suggest v-model="model" placeholder="Text here" type="search">
</vue-simple-suggest>

<!--  Vanilla HTMLInputElement example 3 (fully equivalent to the second example):  -->
<vue-simple-suggest v-model="model">
  <input placeholder="Text here" type="search">
</vue-simple-suggest>

<!--  Vanilla HTMLInputElement example 4 (nested):  -->
<vue-simple-suggest v-model="model">
  <div>
    <section>
      <input type="email">
    </section>
  </div>
</vue-simple-suggest>

<!--  Vue component example (also supports nesting):  -->
<vue-simple-suggest v-model="vModelGoesHere">
  <my-custom-input-somponent :value="initialInputValueGoesHere"></my-custom-input-somponent>
</vue-simple-suggest>

Custom input component caveats:

To work with the vue-simple-suggest your custom input component has to follow certain standard behaviours.

Custom input component must (in order to work properly):

• Emit an input event.
• Emit focus and blur events.
• Have a value prop.

Custom input component should (in order to avoid usage limitations):

• Not stop any event propagations from internal input HTML element.
• Forward an original event argument with focus and blur events.

If vue-simple-suggest with your custom component doesn't seem to react to outside variable changes - bind both components' v-model to the same variable, like so:

<vue-simple-suggest v-model="model">
  <my-custom-input-somponent v-model="model"></my-custom-input-somponent>
</vue-simple-suggest>

Accessibility on custom input

New in v1.9.0

vue-simple-suggest automatically injects 3 necessary ARIA attributes for the default <input> element and any custom input, as long as your custom input component contains an html <input> element.

These attributes ensure that the autocomplete can be used by users who rely on Screen Readers.

Custom suggestion item

suggestion-item slot (optional)

Description

Allows custom html-definitons of the suggestion items in a list. Defaults to <span>{{ displayAttribute(suggestion) }}</span>

Accepts the suggestion object and a query text as a slot-scope attribute values.

<!-- Example (book suggestions): -->
<vue-simple-suggest>
  <div slot="suggestion-item" slot-scope="{ suggestion, query }">
    <div>{{ suggestion.title }} by {{ suggestion.author }}</div>
  </div>
</vue-simple-suggest>

Custom buttons inside of suggestion items

If you want to add some action buttons to the suggetion items, just use the .stop directive modifier to prevent the default suggestion-click:

<!-- Example (editable book suggestion): -->
<vue-simple-suggest>
  <div slot="suggestion-item" slot-scope="{ suggestion, query }">
    <span>{{ suggestion.title }} by {{ suggestion.author }}</span>
    <button @click.stop="remove(suggestion)">remove from list</button>
    <button @click.stop="like(suggestion)">add to favorites</button>
  </div>
</vue-simple-suggest>

In this case, the buttons will ONLY execute the bound method and will not select the suggested item.

Manual autocomplete

If there's a need to autocomplete the suggestion in the input instead of selecting it (like in mobile suggestions of google search), you can use the autocomplete() function in the slot's scope:

<!-- Example: -->
<vue-simple-suggest>
  <div slot="suggestion-item" slot-scope="{ suggestion, autocomplete }">
    <span>{{ suggestion.title }} by {{ suggestion.author }}</span>
    <button @click.stop="autocomplete()">Complete input</button>
  </div>
</vue-simple-suggest>

or in the ref methods:

<template>
  <vue-simple-suggest ref="suggest">
    <div slot="suggestion-item" slot-scope="{ suggestion }">
      <span>{{ suggestion.title }} by {{ suggestion.author }}</span>
      <button @click.stop="onAutocompleteButtonClick(suggestion)">Complete input</button>
    </div>
  </vue-simple-suggest>
</template>

<script>
export default {
  //...
  methods: {
    onAutocompleteButtonClick(suggestion) {
      this.$refs.suggest.autocompleteText(suggestion);
    }
  }
  //...
}
</script>

Ref Data

In cooperation with ref fields this slot can be used to drastically transform the suggestion list behaviour.

One of the simplest examples - highlighting the query text in the results:

<div slot="suggestion-item" slot-scope="scope">
  <span v-html="boldenSuggestion(scope)"></span>
</div>

boldenSuggestion(scope) {
  if (!scope) return scope;

  const { suggestion, query } = scope;

  let result = this.$refs.suggestComponent.displayProperty(suggestion);

  if (!query) return result;

  const texts = query.split(/[\s-_/\\|\.]/gm).filter(t => !!t) || [''];
  return result.replace(new RegExp('(.*?)(' + texts.join('|') + ')(.*?)','gi'), '$1<b>$2</b>$3');
}

Result via Google Books search API:

Custom miscellaneous item slots

misc-item-above and misc-item-below slots (optional)

Allow custom elements to be shown in suggestion list. These elements never dissapear from the list, neither can they be selected nor hovered on.

They can be used for decoration, loaders, error messages and etc.

These slots don't have defaults, so they are not shown until defined.

Accept the suggestions array and a query text as a slot-scope attribute values.

<!-- Examples: -->
<vue-simple-suggest>
  <template slot="misc-item-above" slot-scope="{ suggestions, query }">
    <div class="misc-item">
      <span>You're searching for {{ query }}.</span>
    </div>
    <div class="misc-item">
      <span>{{ suggestions.length }} suggestions are shown...</span>
    </div>
  </template>

  <div slot="misc-item-below" slot-scope="{ suggestions }" v-if="isLoading" class="misc-item">
    <span>Loading...</span>
  </div>
</vue-simple-suggest>

These slots can also be used to handle empty results, like this:

<!-- Main slot template -->
<template slot="misc-item-above" slot-scope="{ suggestions, query }">
  <div class="misc-item">
    <span>You're searching for '{{ query }}'.</span>
  </div>

  <!-- Sub-template if have any suggestions -->
  <template v-if="suggestions.length > 0">
    <div class="misc-item">
      <span>{{ suggestions.length }} suggestions are shown...</span>
    </div>
    <hr>
  </template>

  <!-- Show "No result" otherwise, if not loading new ones -->
  <div class="misc-item" v-else-if="!loading">
    <span>No results</span>
  </div>
</template>

Contributors

Thanks goes to these wonderful people (emoji key):

Alexey 😇	Karen 😐	Simeon Kerkola 💻 📖 🤔	Roberson Costa 💻 📖 🤔	Rosdi Kasim 📖	antoinematyja 🤔	Matthias Martin 🐛
Rob Brain 🐛 🐛	MrWook 🐛	nattam 🤔	Petr 🐛	RMFogarty 💬	Brian Monsales 💬	Mila76 🐛
Andriy Löfberg 💬 🤔 💻	Bruno Monteiro 🤔	hannesaasamets 🐛	Jimmy 🐛	Will Plaehn 💻 🤔 📖	lauri911 🐛	Alex Hyriavets 🐛
Behnood Khani 🐛	Hay Kranen 📖	shrpne 🐛 💻 🤔	Peta Dragos-Andrei 🐛	shoito 📖	yamagen0915 🐛 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!