DOCSEARCHbyAlgolia
Submit Docs

awesomplete

repository·gh-pages·Indexed 27 days ago

https://github.com/leaverou/awesomplete

An ultra-lightweight, customizable, and simple autocomplete widget with zero dependencies for modern browsers. It supports providing suggestions via comma-separated strings, HTML <datalist>, or CSS selectors. Version 1.1.7 includes configurable options for minimum characters, maximum items, and custom filter and sort functions.

Tokens
1.2K
Snippets
1
Records
8
Agent score
42%

What's inside awesomplete

  1. Basic Usage of Awesomplete

    gh-pages

    To use Awesomplete, first include the CSS and JS files in your HTML. You can then enable autocomplete by adding the awesomplete class to an <input> element.

    There are three primary ways to provide suggestions:

    1. Comma-separated string: Use the data-list attribute with a string of items.
    2. HTML <datalist>: Use the list attribute pointing to the ID of a <datalist> for native fallback.
    3. CSS Selector: Use the data-list attribute with a CSS selector (e.g., #id or .class) pointing to a <ul> or similar element.
    <!-- 1. Include assets -->
<link rel="stylesheet" href="awesomplete.css" />
<script src="awesomplete.js" async></script>

<!-- 2. Option A: Comma-separated string -->
<input class="awesomplete" data-list="Ada, Java, JavaScript" />

<!-- 2. Option B: Using <datalist> for native fallback -->
<input class="awesomplete" list="mylist" />
<datalist id="mylist">
  <option>Ada</option>
  <option>Java</option>
</datalist>

<!-- 2. Option C: Using a CSS selector for a list element -->
<input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
  <li>Ada</li>
  <li>Java</li>
</ul>

  3. Configure Awesomplete Options

    gh-pages

    Awesomplete can be customized using JavaScript properties or HTML data-* attributes.

    JS PropertyHTML AttributeDescriptionValueDefault
    listdata-listWhere to find the list of suggestions.Array of strings, HTML element, CSS selector, or comma-separated stringN/A
    minCharsdata-mincharsMinimum characters to type before the popup shows.Number2
    maxItemsdata-maxitemsMaximum number of suggestions to display.Number10
    autoFirstdata-autofirstShould the first element be automatically selected.Booleanfalse
    listLabeldata-listlabelLabel used as aria-label on the generated list.StringResults List

  4. Initialize Awesomplete on input elements

    gh-pages

    Awesomplete can be initialized automatically by adding the awesomplete class to an <input> element. If the DOM is already loaded, it will initialize immediately; otherwise, it waits for DOMContentLoaded.

    Alternatively, you can manually create an instance by calling the Awesomplete constructor with a specific input element and an optional configuration object.

  5. Provide a list of suggestions

    gh-pages

    You can provide the data for the autocomplete list in several ways:

    1. Via Constructor Options: Pass an array to the data option.
    2. Via data-list attribute: Pass a comma-separated string to the input element.
    3. Via list property: Set the .list property on the instance.
    4. Via HTML element: Set the list attribute on the input to a CSS selector of an existing element (e.g., a <datalist> or <ul>). Awesomplete will extract text/values from its children.

    Suggestions can be simple strings or objects with { label, value } properties.

  7. Listen to Awesomplete events

    gh-pages

    The Awesomplete instance fires several custom events on the input element that you can listen to:

    • awesomplete-open: Fired when the list is opened.
    • awesomplete-close: Fired when the list is closed. The event object contains a reason (e.g., 'blur', 'esc', 'select', 'nomatches', 'submit').
    • awesomplete-highlight: Fired when a suggestion is highlighted (via keyboard navigation). Contains { text }.
    • awesomplete-select: Fired when a user attempts to select a suggestion. If the listener returns false, the selection is cancelled. Contains { text, origin, originalEvent }.
    • awesomplete-selectcomplete: Fired after a selection has been successfully applied to the input. Contains { text, originalEvent }.

  8. Use Awesomplete filter and sort functions

    gh-pages

    Awesomplete provides built-in static methods for filtering and sorting that can be used in the configuration object.

    Filtering:

    • Awesomplete.FILTER_CONTAINS: Checks if the input string exists anywhere within the text (case-insensitive).
    • Awesomplete.FILTER_STARTSWITH: Checks if the text starts with the input string (case-insensitive).

    Sorting:

    • Awesomplete.SORT_BYLENGTH: Sorts items by their length (shorter items first).