- Notifications
You must be signed in to change notification settings - Fork74
Feature-rich autocomplete component for Vue.js
License
KazanExpress/vue-simple-suggest
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Simple yet feature-rich autocomplete component for Vue.js
npm install --save vue-simple-suggest
Seeinstallation guide for more options.
- vue-simple-suggest
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.
v-modelsupport.- Automaticaccessibility attributes (WAI-ARIA complete)
- Switching
v-modeltype (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,tabindexand etc...). - Customizablekeyboard controls.
- Rich and simpleAPI.
- 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.
If you feel that something important is missing (or found a bug) - feel free tocreate an issue. :)
To use the component just install via NPM:
npm install --save vue-simple-suggest
Then, in your Vue.js component/page do the following...
If you need to suggest things from a static array:
<!-- Some component.vue --><template><vue-simple-suggestv-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>importVueSimpleSuggestfrom'vue-simple-suggest'import'vue-simple-suggest/dist/styles.css'// Optional CSSexportdefault{components:{ VueSimpleSuggest},data(){return{chosen:''}},methods:{simpleSuggestionList(){return['Vue.js','React.js','Angular.js']}}}</script>
If you're dealing with async data from server (example usinghttps://swapi.co/):
<!-- Some component.vue --><template><vue-simple-suggestv-model="chosen"display-attribute="name"value-attribute="url":list="getSuggestionList"></vue-simple-suggest><br><p>Chosen element: {{ chosen }}</p></template><script>importVueSimpleSuggestfrom'vue-simple-suggest'import'vue-simple-suggest/dist/styles.css'// Optional CSSexportdefault{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(){returnfetch('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 ourexample source.
npm install --save vue-simple-suggest# oryarn add vue-simple-suggestIf including via this method - the component will automatically install itself.
<!-- UMD Component, async/await polyfills through promises --><scripttype="text/javascript"src="https://unpkg.com/vue-simple-suggest"></script><scripttype="text/javascript"src="https://unpkg.com/vue-simple-suggest@1.5.1"></script><!-- Specific version --><!-- CSS --><linkrel="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! --><scripttype="text/javascript"src="https://unpkg.com/vue-simple-suggest/dist/iife.js"></script>
/// ESNext (original code, no pollyfills, single-file .vue component, css included)importVueSimpleSuggestfrom'vue-simple-suggest/lib'////// ES6 (async polyfills)importVueSimpleSuggestfrom'vue-simple-suggest'// or, if you have problems importing:importVueSimpleSuggestfrom'vue-simple-suggest/dist/es6'////// ES7 and above (no polyfills)importVueSimpleSuggestfrom'vue-simple-suggest/dist/es7'////// CommonJS (async, arrow-functions and promises are polyfilled)constVueSimpleSuggest=require('vue-simple-suggest')// or, if you have problems importing:constVueSimpleSuggest=require('vue-simple-suggest/dist/cjs')///// Optional - import css separately with css loaders:import'vue-simple-suggest/dist/styles.css'
New in
v1.8.3
vue-simple-suggest comes with minimal optional polyfills for IE11+ -Object.assign,Element.prototype.closest andElement.prototype.matches.You can import them like this:
import'vue-simple-suggest/lib/polyfills';// orrequire('vue-simple-suggest/lib/polyfills');
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>importVueSimpleSuggestfrom'vue-simple-suggest'import'vue-simple-suggest/dist/styles.css'// Using a css-loaderexportdefault{components:{ VueSimpleSuggest}}</script>
# clone the repogit clone https://github.com/KazanExpress/vue-simple-suggest.gitcd ./vue-simple-suggest# install dependenciesnpm install# serve example with hot reload at localhostnpm run dev# build example & readme for static servingnpm run docs
New inv1.2.0
These are default keyboard shortcuts.
Can be customized with thecontrols prop. All fields in thiscontrols object are optional.
Default scheme:
| Key (key code) | Description |
|---|---|
Escape (27) | If the suggestions list is shown - hide it. Defined byhideList property. |
ArrowDown (40) | If the suggestions list is hidden - show it. Defined byshowList property. |
ArrowUp (38) /ArrowDown (40) | Cycle (hover) through suggestions. Defined byselectionUp/selectionDown properties respectfully. |
Enter (13) | If the list is shown - chooses the highlighted element. Defined byselect property. |
(Ctrl/Shift) + Space (32) | Select the first element in the list. Defined byautocomplete property. Works withCtrl modifier key orShift modifier key. |
(Ctrl/Shift) + Enter (13) | Same as previous, but also hides the suggestions list. |
JS object:
{selectionUp:[38],selectionDown:[40],select:[13],showList:[40],hideList:[27],autocomplete:[32,13]}
Click to expand
<!-- Ref to access the API, v-model for efficient query binding --><vue-simple-suggestref="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 --><inputclass="optional-custom-input"><!-- Appears o top of the list --><templateslot="misc-item-above"slot-scope="{ suggestions, query }"><divclass="misc-item"><span>You're searching for {{ query }}.</span></div><divclass="misc-item"><span>{{ suggestions.length }} suggestions are shown...</span></div><hr></template><divslot="suggestion-item"slot-scope="{ suggestion }"class="custom">{{ suggestion.title }}</div><!-- Appears below the list --><divclass="misc-item"slot="misc-item-below"slot-scope="{ suggestions }"v-if="loading"><span>Loading...</span></div></vue-simple-suggest>
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-suggestv-model="chosen":list="simpleSuggestionList":styles="autoCompleteStyle":destyled=true:filter-by-query="true"></vue-simple-suggest></template><script> ...exportdefault{ ...data(){return{autoCompleteStyle :{vueSimpleSuggest:"position-relative",inputWrapper:"",defaultInput :"form-control",suggestions:"position-absolute list-group z-1000",suggestItem:"list-group-item"}}}, ...}</script>`<stylelang="scss">.z-1000 {z-index:1000;}.hover {background-color:#007bff;color:#fff;}</style>
Scheme:
| Property | Description |
|---|---|
vueSimpleSuggest | Additional classname for component's root element. |
inputWrapper | Additional classname for.input-wrapper element. |
defaultInput | Additional classname forinput element if no custom input component is given. |
suggestions | Additional classname for suggestions listul element. |
miscItemAbove | Classname formisc-item-above slot wrapper (li element itself). |
suggestItem | Additional classname for suggestion itemli element. |
miscItemBelow | Classname formisc-item-below slot wrapper (li element itself). |
New inv1.8.0
You can also define custom list transitions by defining css rules for the transition namedvue-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;}
| Name | Type | Default | Description |
|---|---|---|---|
controlsv1.2.0 | Object | Seedefault controls | Determines the keyboard shortcuts in key-codes (for browser-compatibility purposes). Arrays provide the ability to assign multiple keys to one action. Consists of 5 array fields:selectionUp,selectionDown,select,hideList andautocomplete, all of which are optional. |
max-suggestions | Number | 10 | The maximum amount of suggestions to display. Set to 0 for infinite suggestions. |
min-length | Number | 1 | The minimum amount of symbols in input to trigger suggestion list.vue-simple-suggest starts behaving as a dropdown menu, if the value is 0. |
display-attribute | String | 'title' | The property in a suggestion object to display in a list. Supports dotted paths. |
value-attribute | String | 'id' | The property in a suggestion object to use as a unique key. Supports dotted paths. |
list | Function or Array | () => [] | The array provider function, must accept a query as its only argument. Can return an array or a promise. Can be async. The component behaves as a simple input without this function. |
debounce | Number | 0 | Determines thelist debounce (a time between the input event and a function execution). |
destyled | Boolean | false | Whether to cancel the default styling of input and suggestions list. |
stylesv1.8.0 | Object | {} | CSS classes to attach with current component style. |
remove-list | Boolean | false | If true - the suggestion list will be always hidden. |
filter-by-query | Boolean | false | Whether to filter the resulting suggestions by input's text query (make it a search component). |
filter | Function | - | A custom function for filtering the suggestion results that accepts a single item and a query to filter by as its 2 arguments. Used only iffilter-by-query is set totrue. |
modev1.4.0 | String | 'input' | Thev-model event. Determines the event, that triggersv-model. Can be one of'input' (v-model binds a displayed property) or'select' (v-model binds a selected item). |
type,value,pattern, etc... | All of the HTML5 input attributes with their respected default values. | ||
nullable-selectv1.9.0 | Boolean | false | Whether theselect should acceptnull or not. |
preventHidev1.11.0 | Boolean | false | Whether to keep the input open or not, allowing the user to select multiple inputs |
New inv1.4.0
Determines the event, that triggersv-model. Can be one of'input' (default) or'select'.
For example, if'input' is chosen - then v-model will update the value each time aninput 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-suggestv-model="selected"mode="select"><inputv-model="text"></vue-simple-suggest>
| Name | Arguments | Description |
|---|---|---|
input | HTML input event | An outward projection of the current input's event. |
focus | HTML focus event | An outward projection of the current input's event. |
blur | HTML focus event | An outward projection of the current input's event. |
select | Selected suggestion | Fires on suggestion selection (via a mouse click or enter keypress). |
hover | Hovered suggestion, target element | Fires each time a new suggestion is highlighted (via a cursor movement or keyboard arrows). |
suggestion-click | Selected suggestion, HTML click event | Fires on suggestion element click. |
show-list | - | Fires each time the suggestion list is toggled to be shown. |
hide-list | - | Fires each time the suggestion list is being hidden. |
request-start | Current input value (query) | Fires each time alist function starts executing. |
request-done | Resulting suggestions list | Fires when alist function successfully returns a result and forwards that result as an argument. |
request-failed | The interrrupting exception | Fires if an exception occurs during the execution of alist funciton. |
accessed via
$refs.*your ref name here*
| Name | Arguments | Description |
|---|---|---|
showList | - | Shows the suggestion list. Emits the respectedevent. |
hideList | - | Hides the suggestion list. Emits the respectedevent. |
getSuggestions | query: string | Gets and processes suggestions from thelist prop. Returns a promise. Emits therequestStart,requestDone andrequestFailedevents. |
research | - | DebouncedgetSuggestions on the current input value. |
clearSuggestions | - | Clears thesuggestions array. |
select | suggestion | Selects the passed suggestion. Emits the respectedevent. |
hover | suggestion | Hovers over the passed suggestion. Emits the respectedevent. |
displayProperty | suggestion | Returns the displayed property of a suggestion. |
valueProperty | suggestion | Returns the value property of a suggestion. |
setTextv1.9.0 | text | Reliably sets custom text to the input field. |
autocompleteTextv1.10.0 | suggestion | Autocompletes the input text using the suggestion passed as the only argument. |
accessed via
$refs.*your ref name here*
You can use these to imitate some of the component's behaviours.
| Name | Arguments | Description |
|---|---|---|
onShowList | Invoked when a suggestion list needs to be shown. | |
showSuggestions | Shows suggestion list, refreshes the data if needed. | |
onInput | HTML input event | Invoked whenever the input text is changed. Emits theinput event. |
onFocus | HTML focus event | Invoked whenever the input comes into focus, emits thefocus event. |
onBlur | HTML focus event | Antonym toonFocus. |
onAutocomplete | - | Invoked when the autocompletekeyboard shortcut is pressed. Selects the first suggestion. |
onListKeyUp | HTML keyup event | Invoked on component keyup. Internally used for hiding the list. |
onKeyDown | HTML keydown event | Invoked on component keydown. Internally used for showing the list, updating suggestions and preventing form submit. |
moveSelection | Invoked when hovered element needs to be changed. | |
suggestionClick | suggestion, HTML click event | Invoked on any suggestion click. Can be used to emulate such a click from ouside of the component. |
accessed via
$refs.*your ref name here*
| Name | Default | Description |
|---|---|---|
selected | null | Currently selected element. |
hovered | null | Currently hovered element. |
suggestions | [] | Current suggestions list. |
textLength | 0 | Length of the text in the input. |
listShown | false | Is suggestion list shown. |
inputElement | null | Currently used HTMLInputElement. |
canSend | true | Whether the assigned getListFuncion can be executed. |
timeoutInstance | null | The timeout until next getListFunction execution. |
text | $props.value | Current input text. |
slotIsComponent | false | Whether this current custom input is a vue-component. |
listIsRequest | - | Whether the list prop is a function. |
input | - | A ref to the current input (component or vanilla). |
hoveredIndex | - | The current hovered element index. |
controlScheme | Default Controls | The current controls scheme. |
isPlainSuggestion | false | Whether the current suggestions list consists of plain strings (not objects). |
isClicking | false | true if the user currently clicks. |
isOverList | false | true if the user currently hovers over suggestions list. |
isInFocus | false | true if the component is currently in focus. |
isTabbed | false | true if the user pressed tab, while the component is in focus. |
isSelectedUpToDate | false | true if the user hasn't done any inputs since the last selection, so the selection is still relevant. |
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 asv-model on vue-simple-suggest!
<!-- Default HTMLInputElement example: --><vue-simple-suggestv-model="model"placeholder="Text here"type="search"pattern="[a-z]+"/>
<!-- Vanilla HTMLInputElement example 1: --><vue-simple-suggest><inputpattern="[a-z]+"></vue-simple-suggest>
<!-- Vanilla HTMLInputElement example 2: --><vue-simple-suggestv-model="model"placeholder="Text here"type="search"></vue-simple-suggest>
<!-- Vanilla HTMLInputElement example 3 (fully equivalent to the second example): --><vue-simple-suggestv-model="model"><inputplaceholder="Text here"type="search"></vue-simple-suggest>
<!-- Vanilla HTMLInputElement example 4 (nested): --><vue-simple-suggestv-model="model"><div><section><inputtype="email"></section></div></vue-simple-suggest>
<!-- Vue component example (also supports nesting): --><vue-simple-suggestv-model="vModelGoesHere"><my-custom-input-somponent:value="initialInputValueGoesHere"></my-custom-input-somponent></vue-simple-suggest>
Custom input component caveats:
To work with thevue-simple-suggest your custom input component has to follow certain standard behaviours.
Custom input componentmust (in order to work properly):
- Emit an
inputevent. - Emit
focusandblurevents. - Have a
valueprop.
Custom input componentshould (in order to avoid usage limitations):
- Not stop any event propagations from internal input HTML element.
- Forward an original event argument with
focusandblurevents.
Ifvue-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-suggestv-model="model"><my-custom-input-somponentv-model="model"></my-custom-input-somponent></vue-simple-suggest>
New inv1.9.0
vue-simple-suggest automatically injects 3 necessary ARIA attributes for the default<input> elementand 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.
| Name | Value | Description |
|---|---|---|
| aria-autocomplete | "list" | Indicates that the autocomplete behavior of the text input is to suggest a list of possible values in a popup. |
| aria-controls | IDREF ofsuggestions list | IDREF of the popup element that lists suggested values. |
| aria-activedescendant | IDREF of hovered option | Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the input element. |
suggestion-itemslot (optional)
Description
Allows custom html-definitons of the suggestion items in a list.Defaults to<span>{{ displayAttribute(suggestion) }}</span>
Accepts thesuggestion object and aquery text as aslot-scope attribute values.
<!-- Example (book suggestions): --><vue-simple-suggest><divslot="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 defaultsuggestion-click:
<!-- Example (editable book suggestion): --><vue-simple-suggest><divslot="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 theautocomplete() function in the slot's scope:
<!-- Example: --><vue-simple-suggest><divslot="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 theref methods:
<template><vue-simple-suggestref="suggest"><divslot="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>exportdefault{//...methods:{onAutocompleteButtonClick(suggestion){this.$refs.suggest.autocompleteText(suggestion);}}//...}</script>
Ref Data
In cooperation withref 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:
<divslot="suggestion-item"slot-scope="scope"><spanv-html="boldenSuggestion(scope)"></span></div>
boldenSuggestion(scope){if(!scope)returnscope;const{ suggestion, query}=scope;letresult=this.$refs.suggestComponent.displayProperty(suggestion);if(!query)returnresult;consttexts=query.split(/[\s-_/\\|\.]/gm).filter(t=>!!t)||[''];returnresult.replace(newRegExp('(.*?)('+texts.join('|')+')(.*?)','gi'),'$1<b>$2</b>$3');}
Result via Google Books search API:
misc-item-aboveandmisc-item-belowslots (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 thesuggestions array and aquery text as aslot-scope attribute values.
<!-- Examples: --><vue-simple-suggest><templateslot="misc-item-above"slot-scope="{ suggestions, query }"><divclass="misc-item"><span>You're searching for {{ query }}.</span></div><divclass="misc-item"><span>{{ suggestions.length }} suggestions are shown...</span></div></template><divslot="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 --><templateslot="misc-item-above"slot-scope="{ suggestions, query }"><divclass="misc-item"><span>You're searching for '{{ query }}'.</span></div><!-- Sub-template if have any suggestions --><templatev-if="suggestions.length > 0"><divclass="misc-item"><span>{{ suggestions.length }} suggestions are shown...</span></div><hr></template><!-- Show "No result" otherwise, if not loading new ones --><divclass="misc-item"v-else-if="!loading"><span>No results</span></div></template>
Thanks goes to these wonderful people (emoji key):
This project follows theall-contributors specification. Contributions of any kind are welcome!
About
Feature-rich autocomplete component for Vue.js
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.