Table of Contents

• Examples
• Features
• Installation
• Usage
• Props
• Inspiration
• Contributors
• LICENSE

Examples

• Demo
• Storybook Helpful to see all variations of component's props.
• JSFiddle Helpful for playing around and sharing.
• Codesandbox Demos:
  • Deeply nested data objects as suggestions
  • Api Fetching suggestions with Multiple sections

Features

• WAI-ARIA complete autosuggest component built with the power of Vue.
• Full control over rendering with built in defaults or custom components for rendering.
• Easily integrate AJAX data fetching for list presentation.
• Supports multiple sections.
• No opinions on CSS, full control over styling.
• Rigorously tested.

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save vue-autosuggest

or

yarn add vue-autosuggest

Usage

Load VueAutosuggest into your vue app globally.

import VueAutosuggest from 'vue-autosuggest';
Vue.use(VueAutosuggest);

or locally inside a component:

import { VueAutosuggest } from 'vue-autosuggest';
export default {
  ...
  components: {
      VueAutosuggest
  }
  ...
};

Place the component into your app!

<vue-autosuggest 
    :suggestions="[{data:['Frodo', 'Samwise', 'Gandalf', 'Galadriel', 'Faramir', 'Éowyn']}]"
    :onSelected="clickHandler"
    :inputProps="{id:'autosuggest__input', onInputChange: this.onInputChange, placeholder:'Do you feel lucky, punk?'}"
/>

Advanced usage:

<template>
<div>
    <h1>Vue-autosuggest 🔮</h1>
    <div style="padding-top:10px; margin-bottom: 10px;"><span v-if="selected">You have selected '{{JSON.stringify(selected,null,2)}}'</span></div>
        <vue-autosuggest 
            :suggestions="filteredOptions"
            :onSelected="onSelected"
            :renderSuggestion="renderSuggestion"
            :getSuggestionValue="getSuggestionValue"
            :inputProps="{id:'autosuggest__input', onInputChange: this.onInputChange, placeholder:'Do you feel lucky, punk?'}"/>
</div>
</template>
       
<script>
import { VueAutosuggest } from "vue-autosuggest";

export default {
  components: {
    VueAutosuggest
  },
  data() {
    return {
      selected: "",
      filteredOptions: [],
      suggestions: [
        {
          data: [
            { id: 1, name: "Frodo", avatar: "./frodo.jpg" },
            { id: 2, name: "Samwise", avatar: "./samwise.jpg" },
            { id: 3, name: "Gandalf", avatar: "./gandalf.png" },
            { id: 4, name: "Aragorn", avatar: "./aragorn.jpg" }
          ]
        }
      ]
    };
  },
  methods: {
    onInputChange(text) {
      if (text === null) {
        /* Maybe the text is null but you wanna do 
        * something else, but don't filter by null.
        */
        return;
      }

      // Full cusomizability over filtering
      const filteredData = this.suggestions[0].data.filter(option => {
        return option.name.toLowerCase().indexOf(text.toLowerCase()) > -1;
      });

      // Store data in one property, and filtered in another
      this.filteredOptions = [{ data: filteredData }];
    },
    onSelected(item) {
      this.selected = item;
    },
    renderSuggestion(suggestion) {
      /* You will need babel-plugin-transform-vue-jsx for this kind of full customizable
       * rendering. If you don't use babel or the jsx transform, then you can use this
       * function to just `return suggestion['propertyName'];`
       */ 
      const character = suggestion.item;
      return (
        <div
          style={{
            display: "flex",
            alignItems: "center"
          }}
        >
          <img
            style={{
              width: "25px",
              height: "25px",
              borderRadius: "15px",
              marginRight: "10px"
            }}
            src={character.avatar}
          />{" "}
          <span style={{ color: "navyblue" }}>{character.name}</span>
        </div>
      );
    },
    /**
     * This is what the <input/> value is set to when you are selecting a suggestion.
     */
    getSuggestionValue(suggestion) {
      return suggestion.item.name;
    }
  }
};
</script>

For more advanced usage, check out the examples below, and explore the properties you can use.

Props

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | suggestions | Array | ✓ | Suggestions to be rendered. | | inputProps | Object | ✓ | Add props to the <input>.| | sectionConfigs | Object | | Define multiple sections <input>.| | renderSuggestion | Function | | Tell vue-autosuggest how to render inside the <li> tag. | | getSuggestionValue | Function | | Tells vue-autosuggest what to put in the <input/> value|

inputProps

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | id | String | ✓ | id attribute on <input>.| | onInputChange | Function | ✓ | Triggers everytime the <input> changes.| | onClick | Function | | Triggers everytime the <input> is clicked.| | initialValue | String | | Set some initial value for the <input>.| | Any DOM Props | * | | You can add any props to <input> as the component will v-bind inputProps. Similar to rest spread in JSX. See more details here: https://vuejs.org/v2/api/#v-bind |

sectionConfigs

Multiple sections can be defined in the sectionConfigs prop which defines the control behavior for each section.

| Prop | Type | Required | Description | | :--- | :--- | :---: | :--- | | onSelected | Function | ✓ | Determine behavior for what should happen when a suggestion is selected. e.g. Submit a form, open a link, update a vue model, tweet at Ken Wheeler etc.| | type | String | | Vue component name for specifying which type to implement using Vue's <component :is="componentName"></component> functionality. See DefaultSection.vue for scaffolding a new type. You must declare your component in the scope of the app using Vue.component(). You can extend DefaultSection using extends. See UrlSection for an example.| | limit | Number | | Limit each section by some value. Default: Infinity|

Below we have defined a default section and a blog section. The blog section has a component type of url-section which corresponds to which component the Autosuggest loads. When type is not defined, Vue-autosuggest will use a built in DefaultSection.vue component.

sectionConfigs: {
    'default': {
        limit: 6,
        onSelected: function(item, originalInput) {
            console.log(item, originalInput, `Selected "${item.item}"`);
        }
    },
    'blog': {
        limit: 3,
        type: "url-section",
        onSelected: function() {
            console.log("url: " + item.item.url);
        }
    }
}

renderSuggestion

This function will tell vue-autosuggest how to render the html inside the <li> tag. If you're not using babel-plugin-transform-vue-jsx then this method won't be too beneficial, but if your data is a list of objects you can return a specific object.

renderSuggestion(suggestion) {
    return <div style={{ color: "red" }}>{suggestion.name}</div>;
},

or if you don't use babel or the JSX transform, you can just return the specified object property.

renderSuggestion(suggestion) {
    return suggestion.name;
},

getSuggestionValue

This function will tell vue-autosuggest what to put in the <input/> as the value.

getSuggestionValue(suggestion) {
    return suggestion.name;
},

FAQ

How do I update the input programatically?

• You can assign a ref to the component <vue-autosuggest ref="myRefName" ... /> and then access the input value through this.$refs.myRefName.searchInput. This is useful mainly for clearing the input. ⚠️ Note, refs are more of an "escape hatch" as they call it, so it won't trigger the onInputChange method.

Inspiration

• Misha Moroshko's react-autosuggest component inspired the api + WAI-ARIA completeness https://github.com/moroshko/react-autosuggest
• Spatie inspired the vue component setup + docs https://github.com/spatie/vue-table-component

Contributors

Thanks goes to these people (emoji key):

| Darren Jennings💻 📖 🚇 ⚠️ 🎨 💡 | Evgeniy Kulish💻 🎨 💡 ⚠️ | | :---: | :---: |

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

LICENSE

MIT