search

caroso1222 / amazon-autocomplete

🚀 Unlock the full power of the Amazon autocompletion engine right into your search input. JavaScript Plugin.
https://carlosroso.com/amazon-autocomplete
MIT License
400 stars 38 forks source link

readme

Amazon Autocomplete JS Plugin

npm version size

AmazonAutocomplete is a vanilla JavaScript plugin to unlock the full power of the Amazon autocompletion engine right into your search input.

Demo: http://carlosroso.com/amazon-autocomplete

demo gif

Features

Installation

You can grab the minified file from /dist or unminified from /src but I highly recommend installation through npm. 

npm install --save amazon-autocomplete

Or you can install it using yarn as well:

yarn add amazon-autocomplete

Now add it to your html file:

<html>
  <body>
    ...
    <script src="https://github.com/caroso1222/amazon-autocomplete/raw/master/path/to/amazon-autocomplete.min.js" type="text/javascript"></script>
  </body>
</html>

Usage

Create a text input in your html file for the search field.

<input type="text" id="search-input"/>

Edit your main JavaScript file to create an AmazonAutocomplete instance with your search field CSS selector.

let searchInput = new AmazonAutocomplete('#search-input');

Now you got a search field on steroids. Go ahead and apply some styles to make it shine.

Styling

This is a pretty lightweight JavaScript library so it applies just a few styles to some elements to make it work. You can apply your own styles and customize the look of all the components within the widget. If you’re not that much into CSS, you can grab the following snippet and safely shot it into your stylesheet to get a decent default look. As you can see, AmazonAutocomplete goes all the way BEM.

/* Words container */
.ac__inner{
    background: #f6f6f6;
}

/* Individual word element */
.ac__word{
    margin: 0;
    padding: 5px;
}

/* Word prefix style. It’s the span containing the search keyword within the word. */
.ac__prefix{
    font-weight: bold;
}

/* Style applied to each words while navigating through the list or on hover */
.ac__word--selected, .ac__word:hover{
    background-color: #e3e3e3;
}

Advanced Usage

Configuration

You can customize the plugin behaviour by passing along a config object when instantiating AmazonAutocomplete. These are the properties you can specify:

new AmazonAutocomplete([paramsObject])

Param Type Required Details
selector string Yes CSS selector of the search field.
delay integer No The keyup event on the search field is debounced. This attribute will set the fire rate limit (in milliseconds) on the keyup event callback. Default: 200
showWords boolean No Enable/disable revealing of the words list panel. Can be useful if you want to show the suggested words on your own custom widget. Default: true
hideOnblur boolean No Indicates whether the words list panel should hide when the search field loses focus. Default: true

Events

Each AmazonAutocomplete instance will fire some events. You can susbscribe to these events to, for example, save the selected word in your DB or to show suggested words in your own widget.

Event Callback Param Details
onSelectedWord string This is event is fired when some of the following actions takes place:
  • User clicks a word
  • User navigates through the words list and hits enter
  • User types keyword and hits enter (no suggested word selected)
The callback function will be called with the selected word as its only argument.
onNewWords array This is event is fired when there are new suggested words available. It mostly happens when the keyup event fires on the search field. Keep in mind that the keyup is debounced to improve performance.

Advanced usage example

The next snippet shows how to initialize a AmazonAutocomplete with a 200ms debounce limit, not showing the words panel and not hiding on input text blur. As the words won’t show in the dropdown panel we’ll have to shown them in a custom panel.

//Create the AmazonAutocomplete with our desired properties
let searchInput = new AmazonAutocomplete({
            selector: '#search-input',
            delay: 200,
            showWords: false,
            hideOnblur: false
        });

//Log the selected word to the console
searchInput.onSelectedWord(word => console.log(`searching for ${word}...`));

//Populate your custom panel whenever there are new suggested words available
searchInput.onNewWords(words => words.forEach(word => addWordToCustomPanel(word)));

Features

Licence

AmazonAutocomplete is licensed under MIT licence.