Ultra lightweight, usable, beautiful autocomplete with zero dependencies.

Overview

Awesomplete

npm version Build Status Code Climate Test Coverage

https://leaverou.github.io/awesomplete/

Awesomplete is an ultra lightweight, customizable, simple autocomplete widget with zero dependencies, built with modern standards for modern browsers.

Installation

There are a few ways to obtain the needed files. Here are 2 of them:

  1. CDN server
https://cdnjs.com/libraries/awesomplete
  1. Another way to get up and running is by using yarn or npm:
yarn add awesomplete
npm install awesomplete --save

More information about the npm package can be found here.

Basic Usage

Before you try anything, you need to include awesomplete.css and awesomplete.js in your page, via the usual tags:

<link rel="stylesheet" href="awesomplete.css" />
<script src="awesomplete.js" async></script>

Then you can add an Awesomplete widget by adding the following input tag:

<input class="awesomplete"
       data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />

Add class="awesomplete" for it to be automatically processed (you can still specify many options via HTML attributes) Otherwise you can instantiate with a few lines of JS code, which allow for more customization.

There are many ways to link an input to a list of suggestions. The simple example above could have also been made with the following markup, which provides a nice native fallback in case the script doesn’t load:

<input class="awesomplete" list="mylist" />
<datalist id="mylist">
	<option>Ada</option>
	<option>Java</option>
	<option>JavaScript</option>
	<option>Brainfuck</option>
	<option>LOLCODE</option>
	<option>Node.js</option>
	<option>Ruby on Rails</option>
</datalist>

Or the following, if you don’t want to use a <datalist>, or if you don’t want to use IDs (since any selector will work in data-list):

<input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
	<li>Ada</li>
	<li>Java</li>
	<li>JavaScript</li>
	<li>Brainfuck</li>
	<li>LOLCODE</li>
	<li>Node.js</li>
	<li>Ruby on Rails</li>
</ul>

There are multiple customizations and properties able to be instantiated within the JS. Libraries and definitions of the properties are available in the Links below.

Options

JS Property HTML Attribute Description Value Default
list data-list Where to find the list of suggestions. Array of strings, HTML element, CSS selector (no groups, i.e. no commas), String containing a comma-separated list of items N/A
minChars data-minchars Minimum characters the user has to type before the autocomplete popup shows up. Number 2
maxItems data-maxitems Maximum number of suggestions to display. Number 10
autoFirst data-autofirst Should the first element be automatically Boolean false
listLabel data-listlabel Denotes a label to be used as aria-label on the generated autocomplete list. String Results List

License

Awesomplete is released under the MIT License. See LICENSE file for details.

Links

The official site for the library is at https://leaverou.github.io/awesomplete/.

Documentation for the API and other topics is at https://leaverou.github.io/awesomplete/#api.

Created by Lea Verou and other fantastic contributors.

Comments
  • Various list data formats and separate title/value

    Various list data formats and separate title/value

    New data configuration property is function, which is called for each initial list item in any format to convert it to object like this one:

    { title: "United States", value: "US" }
    

    This object is then used everywhere in API. So instead of item text filter(), sort(), item() and replace() functions now get an object with separate title and value properties.

    Despite this data format change, old code will continue to work as before. This is what Suggestion() shim takes care of. It uses title property when string is expected everywhere in the API.

    The only change is that now we have value property and it would be used in default implementation of replace() method. Suggestion title you see in the completer and the value inserted to the input, when the item is selected can now be fully independent.

    opened by vlazar 35
  • Separate label/value for each suggestion on the list.

    Separate label/value for each suggestion on the list.

    This is an attempt to make a cleaner version of #16851

    To all interested in testing it here is the link to raw version https://raw.githubusercontent.com/vlazar/awesomplete/feature/separate-label-and-value/awesomplete.js Earlier filter(), sort(), item() and replace() were receiving list items as strings. Now they are receiving item as an object with a label and a value. But old API still works via private Suggestion() wrapper which pretends to be a String.

    Known issue with current implementation: suggestion[0] won't work, everything other you expect from String should work fine.

    It is now possible to show a suggestion label in completer, but insert a suggestion value into the input instead.

    In addition to String as before, each list item now can also be:

    • a { label, value } Object
    • a [ label, value ] Array

    To show full country name in completer, but insert country code into the input you can use these items:

    • { label: "United States", value: "US" }
    • [ "United States", "US" ]

    Despite this data format change, old code will continue to work as before. This is taken care by Suggestion(). It uses label property automatically when string is expected anywhere in the API.

    In addition to default support for String/Object/Array items, we also add data method, which can be used to support any additional custom item formats and to generate data dynamically, as in changed Email example. The only thing you need to do in this case is to return item in any of String/Array/Object formats supported by default.

    It's also possible now to have a different label/value via <datalist> element with <option label="United States" value="US">, <option value="US">United States</option> or <option label="United States">US</option>.

    opened by vlazar 25
  • Update input text on autocomplete option highlight

    Update input text on autocomplete option highlight

    Just want to start out by saying that I'd be happy to implement any work that might come out of this issue. I'm more looking for a general +1 on the idea, as well as hash out what the api might look like. With that out of the way...

    Goal: I'm looking to replace a jQuery-UI based autocomplete implementation with Awesomplete. However, for feature parity, I need the input text to update as I navigate through autocomplete choices. More concretely:

    1. A list of autocomplete options are shown (e.g., I've typed "ja" and get the choices "java" and "javascript")
    2. I navigate through the options
    3. As I navigate, the input text updates to reflect the highlighted choice (pressing down once will update the field text to "java" and so on)
      • hitting escape closes the autocomplete dialog and reverts the input text back to the original value ("ja")
      • "selecting" the option works as is already implemented

    I'm fairly confident that this can all be achieved with the existing API. Live-updating the input text is fairly trivial with the awesomplete-highlight event, and the original value can be cached on awesomplete-open. The hacky part comes with the escape functionality, as the code currently makes no distinction between pressing escape and any of the other methods of closing. I might be able to do something with setTimeout / clearTimeout, but it's definitely not ideal, hence this issue.

    So open questions:

    • Is there general value in this behavior? Does it fall inline with the goals of this library?
    • If yes, would this be best wrapped up in a single constructor option (and if so, what's a good name), or would it be preferred to leave much of this in userland and a) expose an update to the escape/blur functionality to either close in a "close and do nothing" state, or b) alternatively fire off a second, more meaningful event? Or something else entirely?
    question 
    opened by jimf 21
  • Outdated npm version

    Outdated npm version

    I get: argument $saturation of hsl($hue, $saturation, $lightness) must be between 0 and 100

    Backtrace: node_modules/awesomplete/awesomplete.css:91, in function hsl

    And here's what line 91 looks like:

    background: hsl(68, 101%, 41%);

    Would be lovely if this could be fixed so that we can keep awesomplete as a node module.

    opened by powerbuoy 19
  • Page demos problems in Firefox 44

    Page demos problems in Firefox 44

    When using the first input in the page https://leaverou.github.io/awesomplete/ it shows as this (double tooltip):

    fireshot capture 2 - awesomplete_ ultra lightweight high_ - https___leaverou github io_awesomplete_

    then after selecting the first item:

    fireshot capture 3 - awesomplete_ ultra lightweight high_ - https___leaverou github io_awesomplete_

    and down with the combobox dropdown, the toggle is misaligned

    fireshot capture 1 - awesomplete_ ultra lightweight high_ - https___leaverou github io_awesomplete_

    bug 
    opened by pocesar 19
  • Capability to differentiate value from displayed text

    Capability to differentiate value from displayed text

    Your library is cool but maybe due to the habit of <select><option> couple for sending identifier, I would like to use a value that differs from the text when event 'awesomplete-selectcomplete' is fired. Another reason could be the fact, that I want to avoid encoding issue. With accents (I'm French), I don't want to bother about encoding client/server when sending info (although nowadays, everyone use UTF-8, in my dreams...) so an identifier is better IMO.

    I don't know if it's a design choice but I didn't see any ways to achieve it. To try to bypass the lib behaviour cleanly, I created the following example below

    <input id="myinput" list="mylist" />
    <datalist id="mylist">
        <option value="a">Ada</option>
        <option value="b">Java</option>
        <option value="c">JavaScript</option>
        <option value="d">Brainfuck</option>
        <option value="e">LOLCODE</option>
        <option value="f">Node.js</option>
        <option value="g">Ruby on Rails</option>
    </datalist>
    
    <script>
    document.querySelector('#myinput').addEventListener('awesomplete-selectcomplete', function(evt){
      console.log(this.value);
    })
    </script>
    

    Unfortunately, it echoed Python but never a when choosing the first option.

    I could always do the below really dirty solution but I would prefer to avoid it.

    What is the way to go for my requirements if any? Thanks for your input.

    document.querySelector('#myinput').addEventListener('awesomplete-selectcomplete', function(evt) {
      var lib = this.value;
      var val = Array.prototype.slice.call(document.querySelectorAll('#mylist option')).filter(function(option) {
        if (option.text == lib) {
          return true;
        };
        return false;
      })[0].value;
      console.log(lib, val);
    });
    
    opened by ThomasG77 18
  • Feature/handle array of objects

    Feature/handle array of objects

    Addresses #16788 by attaching the selected item's dataset to the event object that is passed when the awesomplete-select and awesomplete-selectcomplete events are fired.

    In cases where out list is an array of objects, this allows adding data-* attributes to the lis when building the items based on keys in the object, and then accessing them when the awesomplete-select and awesomplete-selectcomplete events are fired.

    opened by TxHawks 15
  • Emit close reason with awesomplete-close events

    Emit close reason with awesomplete-close events

    Emit a reason when firing awesomplete-close events to provide transparency to attached event listeners regarding the circumstance in which the close was triggered. Reasons include blur, esc, submit, select, and nomatches.

    Closes #16897

    opened by jimf 12
  • Feature/pass target to awesomplete select

    Feature/pass target to awesomplete select

    Addresses #16818

    I'm not happy with option named target though.

    Since an awesomplete-select is fired on INPUT, inside it this, event.target and event.currentTarget are references to INPUT originally. In click target is a reference to clicked element, but in awesomplete-select it may be misleading.

    Eventually we need to pass 2 elements to awesomplete-select event for new features:

    • first one is in this request - exact clicked item (child of LI or LI itself)
    • second is always LI (selected element)

    I can't come up with good aligned names for those 2 new fields in awesomplete-select event.

    Any ideas?

    opened by vlazar 12
  • multiple data selection not working

    multiple data selection not working

    Hi there,

    great library, but I am having trouble getting multiple data selection to work. Here is a minimal example for reproduction

    http://codepen.io/anon/pen/KVzbJj

    Any idea, why this is not working as intended? I tried using data-list attribute as well as a complete data-list tag. In my application (not in the codepen above) I also tried configuring the setting in JS rather than HTML. I tried taking a look at the code, but could not find the segment dealing with this feature.

    Any help is appreciated, thanks.

    opened by tolry 12
  • Pass the original event on select

    Pass the original event on select

    Sometimes we need to know the exact element that was clicked on when selecting an item in the dropdown. This PR adds the original event to the select data when firing the awesomplete-select event.

    opened by gabesoft 12
  • Ability to add data to the label that is not searchable

    Ability to add data to the label that is not searchable

    We have been working with your autocomplete library for quite some time now and we love it, but our need to include stylings in the label has grown to maintain consistency with the use of icons and stylings from our framework.

    Is there a way to include text (preferably markup) that could be rendered to the list output but not searched upon? We've tried a multitude of hacky methods that have all failed us. String replacements, HTML entities, etc. all end up either not be rendered or still being searchable.

    We want to be able to include icons from FontAwesome in the label as well as HTML markup tags to help facilitate the styling of the autocomplete list. Naturally, we thought about adding an additional parameter to the data components and call it display_label which would be used strictly for the render and still allow the label to searched upon but we wanted to see if you had a more cohesive or natural method since I suspect this would dork up the marking feature. At least for us, the marking is not necessary if we could score a win with non-searchable characters in the label.

    Thank you for your time!

    opened by daviegravy 1
  • New release

    New release

    Hi

    The library in cdnjs.com has a lack of the file awesomplete.min.js.map and when used from this site it thrwos a 404 error. I have opened a issue in cdnjs.com packages (https://github.com/cdnjs/packages/issues/1119#issuecomment-1121529378) and was solved, but until a new release is launched the file don' get uploaded to cdnjs.com.

    Is feasible a 1.1.5.1 release ? Or we need to load the libray in other way?

    Thx in advance

    opened by Lofesa 0
  • "Dirty" version on NPM

    Hi, @LeaVerou !

    I don't know what happened, but the version available com https://registry.npmjs.org/awesomplete/-/awesomplete-1.1.5.tgz isn't the last one, despite what the package.json says.

    Is there something I can do to help?

    opened by robsonsobral 3
  • i18n support

    i18n support

    Would be great to have a possibilty to translate the screen reader message, e.g. "list item 1 of 10", or "no results found" in order to support users that don't speak English

    enhancement help wanted 
    opened by bertolami 1
Releases(v1.1.5)
Owner
Lea Verou
Elected @w3ctag member, CSS WG Invited Expert, HCI researcher at MIT CSAIL. Founder of many open source projects, PrismJS probably being the most popular one.
Lea Verou
A jQuery UI plugin to handle multi-tag fields as well as tag suggestions/autocomplete.

Tag-it: a jQuery UI plugin Tag-it is a simple and configurable tag editing widget with autocomplete support. Homepage Demo Check the examples.html for

Alex Ehlke 2.5k Dec 20, 2022
Add Github like mentions autocomplete to your application.

⚠️ Announcement ⚠️ This project was no longer maintained. You could use zurb tribute instead. An autocompletion library to autocomplete mentions, smil

Harold.Luo 5.3k Dec 19, 2022
Lightweight analytics abstraction layer for tracking page views, custom events, & identifying visitors

A lightweight analytics abstraction library for tracking page views, custom events, & identify visitors. Designed to work with any third-party analyti

David Wells 1.9k Dec 31, 2022
Ultra lightweight, usable, beautiful autocomplete with zero dependencies.

Awesomplete https://leaverou.github.io/awesomplete/ Awesomplete is an ultra lightweight, customizable, simple autocomplete widget with zero dependenci

Lea Verou 6.9k Jan 2, 2023
Autocomplete - Simple accessible autocomplete for vanilla javacript with support for remote & local data, ~3KB gzip

Autocomplete - Simple accessible autocomplete for vanilla javacript with support for remote & local data, ~3KB gzip

Grzegorz Tomicki 58 Dec 24, 2022
A beautiful, responsive, highly customizable and accessible replacement for JavaScript's popup boxes. Zero dependencies.Alerts ,dialogs

AsgarAlert (v1) for JS Install <script defer src="/asgar-alert.js"></script> Examples The most basic message: asgar("Hello world!"); A message signali

Asgar Aliyev 5 Dec 20, 2022
1KB lightweight, fast & powerful JavaScript templating engine with zero dependencies. Compatible with server-side environments like node.js, module loaders like RequireJS and all web browsers.

JavaScript Templates Contents Demo Description Usage Client-side Server-side Requirements API tmpl() function Templates cache Output encoding Local he

Sebastian Tschan 1.7k Jan 3, 2023
Zero dependencies, lightweight, and asynchronous https requests package.

This project is a Work in Progress and currently in development. The API is subject to change without warning. A small fetching package for super simp

Ray Arayilakath 11 Dec 8, 2022
Lightweight (zero dependencies) library for enabling cross document web messaging on top of the MessageChannel API.

Lightweight (zero dependencies) library for enabling cross document web messaging on top of the MessageChannel API.

LironH 4 Jul 15, 2022
A simple and minimal, ultra-lightweight vanilla JS framework with 0 deps.

piss.js A simple and minimal, ultra-lightweight vanilla JS framework with 0 deps, containing one function, piss. This function has the background colo

grian 15 Oct 21, 2022
🍭 search-buddy ultra lightweight javascript plugin that can help you create instant search and/or facilitate navigation between pages.

?? search-buddy search-buddy is an open‑source ultra lightweight javascript plugin (* <1kb). It can help you create instant search and/or facilitate n

Michael 4 Jun 16, 2022
An ultra-lightweight self-hosted CI solution with a dashboard and containerized runners

An extremely simple containerized CI server. Ecosystem The Candor ecosystem is straightforward, and entirely containerized. Docker runs on the host ma

Paul Huebner 8 Nov 20, 2022
Zero Two Bot,A fully Modular Whatsapp Bot to do everything possible in WhatsApp by Team Zero Two

?? ???????? ?????? ???? ?? A Moduler WhatsApp Bot designed for both PM and Groups - To take your boring WhatsApp usage into a whole different level. T

Sam Pandey 69 Dec 25, 2022
Multiplies a number by zero. Useful for when you need to multiply a number by zero

multiply-by-zero Multiplies a number by zero. Useful for when you need to multiply a number by zero Please consider checking out the links of this pro

Dheirya Tyagi 2 Jul 3, 2022
Simple, responsive, modern SVG Charts with zero dependencies

Frappe Charts GitHub-inspired modern, intuitive and responsive charts with zero dependencies Explore Demos » Edit at CodePen » Contents Installation U

Frappe 14.6k Jan 4, 2023
Minimalistic, animated SVG gauge. Zero dependencies

SVG Gauge Minmalistic, configurable, animated SVG gauge. Zero dependencies Buy me a coffee ☕ If you like my work please consider making a small donati

Aniket Naik 264 Dec 17, 2022
JavaScript syntax highlighter with language auto-detection and zero dependencies.

Highlight.js Highlight.js is a syntax highlighter written in JavaScript. It works in the browser as well as on the server. It can work with pretty muc

highlight.js 20.8k Jan 5, 2023
A zero-dependencies script to generate sponsors SVG from Patreon

sponsors A zero-dependencies script to generate sponsors SVG from Patreon. Usage Go to https://www.patreon.com/portal/registration/register-clients to

Bjorn Lu 3 Apr 25, 2022
👌A useful zero-dependencies, less than 434 Bytes (gzipped), pure JavaScript & CSS solution for drop an annoying pop-ups confirming the submission of form in your web apps.

Throw out pop-ups confirming the submission of form! A useful zero-dependencies, less than 434 Bytes (gzipped), pure JavaScript & CSS solution for dro

Vic Shóstak 35 Aug 24, 2022
An ultra-light UI runtime

forgo Forgo is a 4KB library that makes it super easy to create modern web apps using JSX (like React). Unlike React, there are very few framework spe

null 322 Dec 22, 2022