Skip to content

Files

Latest commit

 

History

History
 
 

docs

Introduction

License GitHub package.json version npm GitHub top language [Zero Dependencies]() [Size]() Maintained npm Open Source Love



autoComplete.js

Simple autocomplete pure vanilla Javascript library. 🚀 Live Demo v8.3

autoComplete.js is a simple pure vanilla Javascript library that's progressively designed for speed, high versatility and seamless integration with a wide range of projects & systems, made for users and developers in mind.

Features

  • Pure Vanilla Javascript
  • Zero Dependencies
  • Simple & Easy to use
  • Extremely Lightweight
  • Blazing Fast
  • Versatile
  • Hackable & highly customizable

autoComplete.js Code Example

1. Get Started

Clone:

  • Clone autoComplete.js to your local machine
git clone https://github.com/TarekRaafat/autoComplete.js.git

Setup:

  1. Install Dependencies
npm i
  1. For Development
npm run dev
  1. Build Production Package
npm run build

Installation:

  • jsDelivr Logo CDN

CSS

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@8.3.2/dist/css/autoComplete.min.css">

JS

<script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@8.3.2/dist/js/autoComplete.min.js"></script>
  • cdnjs Logo CDN

CSS

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tarekraafat-autocomplete.js/8.3.2/css/autoComplete.min.css">

JS

<script src="https://cdnjs.cloudflare.com/ajax/libs/tarekraafat-autocomplete.js/8.3.2/js/autoComplete.min.js"></script>
  • unpkg Logo CDN

CSS

<link rel="stylesheet" href="https://unpkg.com/@tarekraafat/autocomplete.js@8.3.2/dist/css/autoComplete.css">

JS

<script src="https://unpkg.com/@tarekraafat/autocomplete.js@8.3.2/dist/js/autoComplete.min.js"></script>
  • HTML Logo HTML Local load
<script src="./autoComplete.js"></script>
  • HTML Logo HTML Local load - ES6 module (Use with Import)
<script src="./index.js" type="module"></script>
  • Javascript Logo Import module ES6
import autoComplete from "./autoComplete";
  • install (Node Package Manager)
npm i @tarekraafat/autocomplete.js
  • Yarn Logo install (Javascript Package Manager)
yarn add @tarekraafat/autocomplete.js
  • Node.js Node.js
const autoComplete = require("@tarekraafat/autocomplete.js/dist/js/autoComplete");

How to use:

HTML file

  1. Place the CSS stylesheet inside the HEAD tag
<link rel="stylesheet" href="./css/autoComplete.css">
OR
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@8.3.2/dist/css/autoComplete.min.css">
  1. Assign the default id value "autoComplete" to the desired input field or use any custom id/class and configure the API selector accordingly in Step 4
<input id="autoComplete" tabindex="1">	<!-- Default "id" value = "autoComplete"> -->
  1. Place autoComplete JS file & the custom JS file at the bottom BODY tag
<script src="./js/autoComplete.min.js"></script>
<script src="./js/index.js"></script>
OR
<script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@8.3.2/dist/js/autoComplete.min.js"></script>
<script src="./js/index.js"></script>

Custom JS file

  1. Create new instance of autoComplete engine and configure it NOT all API configurations are required
new autoComplete({
    data: {							  // Data src [Array, Function, Async] | (REQUIRED)
      src: async () => {
        // API key token
        const token = "this_is_the_API_token_number";
        // User search query
        const query = document.querySelector("#autoComplete").value;
        // Fetch External Data Source
        const source = await fetch(`https://www.food2fork.com/api/search?key=${token}&q=${query}`);
        // Format data into JSON
        const data = await source.json();
        // Return Fetched data
        return data.recipes;
      },
      key: ["title"],
      cache: false
    },
    query: {                             // Query Interceptor               | (Optional)
          manipulate: (query) => {
            return query.replace("pizza", "burger");
          }
    },
	sort: (a, b) => {				    // Sort rendered results ascendingly | (Optional)
		if (a.match < b.match) return -1;
	    if (a.match > b.match) return 1;
	    return 0;
    },
	placeHolder: "Food & Drinks...",	 // Place Holder text 				| (Optional)
    selector: "#autoComplete",		   // Input field selector 			 | (Optional)
    observer: true,                      // Input field observer | (Optional)
	threshold: 3,						// Min. Chars length to start Engine | (Optional)
	debounce: 300,					   // Post duration for engine to start | (Optional)
    searchEngine: "strict",			  // Search Engine type/mode 		  | (Optional)
    resultsList: {					   // Rendered results list object 	 | (Optional)
		container: source => {
			source.setAttribute("id", "food_list");
		},
		destination: "#autoComplete",
		position: "afterend",
		element: "ul"
	},
	maxResults: 5,						 // Max. number of rendered results | (Optional)
    highlight: {
        render: true,                    // Highlight matching results        | (Optional)
    }
	resultItem: {	  					// Rendered result item 		   | (Optional)
		content: (data, source) => {
			source.innerHTML = data.match;
		},
		element: "li"
    },
    noResults: (dataFeedback, generateList) => {
        // Generate autoComplete List
        generateList(autoCompleteJS, dataFeedback, dataFeedback.results);
        // No Results List Item
        const result = document.createElement("li");
        result.setAttribute("class", "no_result");
        result.setAttribute("tabindex", "1");
        result.innerHTML = `<span style="display: flex; align-items: center; font-weight: 100; color: rgba(0,0,0,.2);">Found No Results for "${dataFeedback.query}"</span>`;
        document.querySelector(`#${autoCompleteJS.resultsList.idName}`).appendChild(result);
    },
	onSelection: feedback => {			 // Action script onSelection event | (Optional)
		console.log(feedback.selection.value.image_url);
	}
});

API Configuration:


Keys Description Values Default
data Data Source, Data Key, Data Caching & Data Results 1- src:
- Array of Strings / Objects
OR
- Function ( ) => Array of Strings / Objects
2- key:
- Array of Strings
Required if src is Object, for search to point to desired keys
3- Cache:
- true for static data src
- false for dynamic data src "API" with queries
4- Results:
- (list) => Array of Strings / Objects
Data src
trigger Engine event & condition trigger 1- event:
- Array of Strings
2- condition:
- Function (query) => Condition String
1- event: ["input"]
2- condition:
(query.length > this.threshold && query !== " ")
query Query Interceptor - Object with 1 method
1- manipulate: Function with (query) parameter
Raw Input
sort Sort rendered results - Function (firstResult, secondResult) => { ... } false (Random Results)
placeHolder Place Holder text - String Blank / Empty
selector Input field selector - String id/class
OR
- Function ( ) => document.querySelector("")
"#autoComplete"
observer Input field observer - Boolean false
threshold Minimum characters length before engine starts rendering results - Number 1
debounce Minimum duration after typing idle state for engine to kick in - Number
Milliseconds value
debounce: 300
0
searchEngine Search Engine Type/Mode - "strict" lowerCase string
OR
- "loose" lowerCase string
OR
- customEngine Function (query, record) => each match individually
"strict"
diacritics Search Engine Diacritics handler - Boolean false
resultsList Rendered results list destination, position, element & navigation - Object with 8 methods
1- render: Boolean
2- container:
Function (source) => { ... }
3- destination:
- String String id/class
OR
- Function ( ) => document.querySelector("")
4- position:
"beforebegin", "afterbegin", "beforeend", "afterend" lowerCase string
5- element:
"ul", "span", "div" or Custom
6- idName: "id"
7- className: "class"
8- navigation: Function (event, input, resListElement, onSelection, resListData) => { ... }
1- render: true
2- container: (source) => { ... }
3- destination: "#autoComplete"
4- position: "afterend"
5- element: "ul"
6- idName: "autoComplete_list"
7- className: "autoComplete_list"
8- navigation: default
resultItem Rendered result Item content & element - Object with 4 methods
1- content:
- Function (data, source) => { ... }
- data.match has to be used for Highlighted result
2- element:
"li", "span", "div" or Custom
3- idName: "id
4- className: "class
1- content: (data, source) => { ... }
2- element: "li"
3- idName: "autoComplete_result"
4- className: "autoComplete_result"
noResults Action script on noResults found - Function (dataFeedback, generateList) => { ... } No Action
selection Format selected result item - Object with 1 method
1- className: "class"
1- className: autoComplete_selected
highlight Highlight matching results - Object with 2 methods
1- render: Boolean
2- className: "class"
1- render: false
2- className: autoComplete_highlighted
maxResults Maximum number of displayed results - Number 5
feedback Action script on dataFeedback event - Function (data) => { ... } No Action
onSelection Action script onSelection event - Function (feedback) => { ... } No Action
  1. That's it, you're ready to go!

Life Cycle Events:

  1. init: Fires after "autoComplete.js" engine is initialized
  2. fetch: Fires after fetching data is complete
  3. input: Fires on every user input
  4. results: Fires after search is done and matching results are ready
  5. rendered: Fires after rendering the results list
  6. navigation: Fires on every "resultsList" navigation interaction
  7. unInit: Fires after "autoComplete.js" engine is un-initialized

2. Examples

  • Live working Demo

  • Try it on CodePen Logo

  • Download Demo files locally from /dist folder

3. Third-Party Plugins


4. Support

For general questions about autoComplete.js, tweet at @TarekRaafat.

For technical questions, you should post a question on Stack Overflow and tag it with autoComplete.js.


5. Browsers Support

IE / Edge
IE / Edge
Firefox
Firefox
Chrome
Chrome
Safari
Safari
iOS Safari
iOS Safari
Samsung
Samsung
Opera
Opera
Opera Mini
Opera Mini
Electron
Electron
Edge last version last version last version last version last version last version last version last version

6. What's New in v8.3?

Check out Releases Information ✨


7. Roadmap

Functionality:

  • Add support for different types of data source
    • Function
    • JSON
    • Array of Object
    • External data source via Promises & Async/Await function
  • Multi-keyword Search
  • Different types/modes of Search Logic
  • Choose different results render destination & position
  • Sort rendered results
  • Results list Keyboard ARROW or TAB Navigation
  • Enhance error Handling (Ongoing)
  • Number of matching results
  • Fetching dynamically External API data source
  • Multiple searchable keys for data src
  • Event emitter on input field events
  • Handling large data sets
  • Event emitter fires on cleared empty input field state
  • Query Interception & Manipulation
  • Improve Promise usage for external data source handling
  • Add support for Diacritics
  • Input field Observer
  • Automatic deep search over all keys in multiple nested object data source

Usability:

  • Avail Gzip files options
  • Comprehensive data feedback on user selection
  • Dynamic input field selector
  • Minimum characters length before results start getting rendered for more focused results
  • No matches found response & text
  • API for Rendered result item customization
  • API for Rendered results list customization
  • Capability for multiple instances
  • Render results in default case
  • Render resultsList & resultItem in different/custom elements
  • HTML elements ContentEditable Input Support
  • Serve results without rendering list through resultsList.render API
  • Custom Search Engine Capability
  • ShadowDom Support
  • API support for customNavigation
  • API support for customEventTriggers & customTriggerConditions
  • Better resultsList navigation [Without loosing cursor]
  • Add event emitters for navigation
  • Life Cycle Events
  • Add more use examples & cases of the library to the documentation
  • Better code compression / optimization for the library to squeeze it back under [5kb]

Plugins:

  • Recent / Most Searches
  • Inline Suggestions
  • Input Tags
  • Virtual Scrolling
  • Results List Category Separator
  • IndexedDB for large data sets handling & offline usage
  • Themes / Styles & Interactions

Styles:

  • autoComplete.js default style
  • Neutral style [01]
  • Light style [02]

Reported Issues:

  • Duplicated results when using multiple data source keys

8. Contribution

Contributions are always more than welcome!

If you have any ideas, just open an issue and tell me what you think.

  • Please fork the repository and make changes as you'd like. Pull requests are warmly welcome.

If you'd like to contribute:

  1. Fork it (https://github.com/TarekRaafat/autoComplete.js.git)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request

9. Author

Tarek Raafat

Distributed under the Apache 2.0 license. See Apache 2.0 for more information.


10. License

Apache 2.0 © Tarek Raafat