Auto-Complete
Demos & Examples
Overview
The auto-complete plugin creates a keyboard navigable dropdown list of options beneath an input element. The options list supports list retrieval via attribute, an inline element, or AJAX. Lists formats can be either a comma-separated list of values or a pre-existing HTML list, which means that that the dropdown list can use images, links, and other interactive features.
Usage
To start using the auto-complete plugin, add a class of autocomplete to any text input
element. While numerous options are available, the two required options that you must set via data
attributes are data-source and data-options.
The data-source attribute tells the plugin where it will be able to find the list of
options. Possible values are:
attribute- The options are a CSV list found in thedata-optionsattribute. (Use this for short lists only).inlineCSV- The options are a CSV list found in an onpage element.inlineHTML- The options are an HTML list found in an onpage element.ajaxCSV- The options are a CSV list retrieved via AJAX.ajaxHTML- The options are an HTML list retrieved via AJAX.
The value of the data-options attribute will depend on the value of the
data-source attribute. Here are the corresponding values for data-options
for each possible value of data-source:
attribute- A CSV list of options.inlineCSV- The id of the CSV list container element, minus the#.inlineHTML- The id of the HTML list container element, minus the#.ajaxCSV- The URL of the CSV list to be retrieved via AJAX.ajaxHTML- The URL of the HTML list to be retrieved via AJAX.
AJAX Queries
When retrieving a list of options via AJAX, the input's current value will be passed through to the
target URL using GET. The default URL parameter is q, but you can customize this with
the data-query attribute.
Warning For security purposes, you will need to properly handle the query parameter at your target URL to prevent SQL injections and other security issues. The auto-complete plugin does not sanitize or secure the input's data in any way.
Options
| Auto-complete Options | ||||
|---|---|---|---|---|
| Option | Description | Required | Default | Values |
data-source |
The source of the autocomplete list. | required | none | attribute | inlineCSV | inlineHTML | ajaxCSV | ajaxHTML |
data-options |
The comma-separated options for the lookup if data-source is
attribute. If the options are stored in an inline element, the value for
data-options should be the container id for the options. If the options
are retrieved via an AJAX, the value should be the URL from where the options can be
retrieved. |
required | none | mixed |
data-query |
The URL query parameter to be used for AJAX lookups. | optional | q | string |
data-min |
The minimum number of characters that will trigger the autocomplete lookup. | optional | 1 | integer |
data-limit |
The maximum number of results to display at a time. | optional | 5 | integer |
data-sort |
Whether or not the data should be auto-sorted | optional | true | boolean |
data-prompt |
The prompt to be shown when the input is first focused. Note The prompt will only be show if the attribute is present. | optional | none | string |
data-loading |
The prompt to be shown when the results are being loaded. | optional | loading | string |
data-empty |
The prompt to be shown when no results are found. | optional | No results found | string |
Events
| Event | Description |
|---|---|
completed |
The completed event is fired for the form input field when an auto-complete option has been selected from the list. |
Demos
Attribute List
<form> <label for="favorite">What's your favorite food that starts with a P?</label> <input type="text" id="favorite" name="favorite" class="autocomplete" data-source="attribute" data-options="Pizza,Pie,Potatoes,Pork,Papaya,Pecans,Peanut Butter,Peaches,Pancakes" /> </form>
Inline CSV List
Alabama,Alaska,Arizona,Arkansas,California,Colorado,
Connecticut,Delaware,District of Columbia,Florida,Georgia,Hawaii,Idaho,Illinois,Indiana,Iowa,Kansas,
Kentucky,Louisiana,Maine,Montana,Nebraska,Nevada,New Hampshire,New Jersey,New Mexico,New York,
North Carolina,North Dakota,Ohio,Oklahoma,Oregon,Maryland,Massachusetts,Michigan,Minnesota,
Mississippi,Missouri,Pennsylvania,Rhode Island,South Carolina,South Dakota,Tennessee,Texas,Utah,
Vermont,Virginia,Washington,West Virginia,Wisconsin,Wyoming
<form> <label for="states">Name a US state</label> <input type="text" id="states" name="states" class="autocomplete" data-source="inlineCSV" data-options="statesList" /> </form> <div id="statesList" class="hidden">Alabama,Alaska,Arizona,Arkansas,California,Colorado,Connecticut,Delaware, District of Columbia,Florida,Georgia,Hawaii,Idaho,Illinois,Indiana,Iowa,Kansas,Kentucky,Louisiana,Maine,Montana, Nebraska,Nevada,New Hampshire,New Jersey,New Mexico,New York,North Carolina,North Dakota,Ohio,Oklahoma,Oregon, Maryland,Massachusetts,Michigan,Minnesota,Mississippi,Missouri,Pennsylvania,Rhode Island,South Carolina, South Dakota,Tennessee,Texas,Utah,Vermont,Virginia,Washington,West Virginia,Wisconsin,Wyoming</div>
Inline HTML List
John
Jacob
Benjamin- Adam
Jane
Johanna
Chris
Peter- Suzy
- Lynn
- Jennifer
- Meghan
- Andrew
- Jeff
- Robert
- Angela
<form> <label for="names">Pick a baby name</label> <input type="text" id="names" name="names" class="autocomplete" data-source="inlineHTML" data-options="namesList" /> </form> <div id="namesList" class="hidden"> <ul class="autocompleteList"> <li data-item="John"><img class="skipBaseline" src="../images/smilies/smiley-1.png"/><span class="text">John</span></li> <li data-item="Jacob"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jacob</span></li> <li data-item="Benjamin"><img class="skipBaseline" src="../images/smilies/smiley-3.png"/><span class="text">Benjamin</span></li> <li data-item="Adam"><img class="skipBaseline" src="../images/smilies/smiley-3.png"/><span class="text">Adam</span></li> <li data-item="Jane"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Jane</span></li> <li data-item="Johanna"><img class="skipBaseline" src="../images/smilies/smiley-7.png"/><span class="text">Johanna</span></li> <li data-item="Chris"><img class="skipBaseline" src="../images/smilies/smiley-5.png"/><span class="text">Chris</span></li> <li data-item="Peter"><img class="skipBaseline" src="../images/smilies/smiley-6.png"/><span class="text">Peter</span></li> <li data-item="Susy"><img class="skipBaseline" src="../images/smilies/smiley-5.png"/><span class="text">Suzy</span></li> <li data-item="Lynn"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Lynn</span></li> <li data-item="Jennifer"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jennifer</span></li> <li data-item="Meghan"><img class="skipBaseline" src="../images/smilies/smiley-6.png"/><span class="text">Meghan</span></li> <li data-item="Andrew"><img class="skipBaseline" src="../images/smilies/smiley-1.png"/><span class="text">Andrew</span></li> <li data-item="Jeff"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jeff</span></li> <li data-item="Robert"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Robert</span></li> <li data-item="Angela"><img class="skipBaseline" src="../images/smilies/smiley-7.png"/><span class="text">Angela</span></li> </ul> </div>
AJAX CSV List
On-Page Code
<form> <label for="states">Name a US state</label> <input type="text" id="states2" name="states2" class="autocomplete" data-source="ajaxCSV" data-options="../ajax/autocomplete-csv.html" /> </form>
autocomplete-csv.html
Alabama,Alaska,Arizona,Arkansas,California,Colorado,Connecticut,Delaware,District of Columbia,Florida,Georgia,Hawaii, Idaho,Illinois,Indiana,Iowa,Kansas,Kentucky,Louisiana,Maine,Montana,Nebraska,Nevada,New Hampshire,New Jersey,New Mexico, New York,North Carolina,North Dakota,Ohio,Oklahoma,Oregon,Maryland,Massachusetts,Michigan,Minnesota,Mississippi, Missouri,Pennsylvania,Rhode Island,South Carolina,South Dakota,Tennessee,Texas,Utah,Vermont,Virginia,Washington,West Virginia,Wisconsin,Wyoming
AJAX HTML List
On-Page Code
<form> <label for="states">Pick a baby name</label> <input type="text" id="names2" name="names2" class="autocomplete" data-source="ajaxHTML" data-options="../ajax/autocomplete-html.html" /> </form>
autocomplete-html.html
<ul class="autocompleteList"> <li data-item="John"><img class="skipBaseline" src="../images/smilies/smiley-1.png"/><span class="text">John</span></li> <li data-item="Jacob"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jacob</span></li> <li data-item="Benjamin"><img class="skipBaseline" src="../images/smilies/smiley-3.png"/><span class="text">Benjamin</span></li> <li data-item="Adam"><img class="skipBaseline" src="../images/smilies/smiley-3.png"/><span class="text">Adam</span></li> <li data-item="Jane"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Jane</span></li> <li data-item="Johanna"><img class="skipBaseline" src="../images/smilies/smiley-7.png"/><span class="text">Johanna</span></li> <li data-item="Chris"><img class="skipBaseline" src="../images/smilies/smiley-5.png"/><span class="text">Chris</span></li> <li data-item="Peter"><img class="skipBaseline" src="../images/smilies/smiley-6.png"/><span class="text">Peter</span></li> <li data-item="Suzy"><img class="skipBaseline" src="../images/smilies/smiley-5.png"/><span class="text">Suzy</span></li> <li data-item="Lynn"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Lynn</span></li> <li data-item="Jennifer"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jennifer</span></li> <li data-item="Meghan"><img class="skipBaseline" src="../images/smilies/smiley-6.png"/><span class="text">Meghan</span></li> <li data-item="Andrew"><img class="skipBaseline" src="../images/smilies/smiley-1.png"/><span class="text">Andrew</span></li> <li data-item="Jeff"><img class="skipBaseline" src="../images/smilies/smiley-2.png"/><span class="text">Jeff</span></li> <li data-item="Robert"><img class="skipBaseline" src="../images/smilies/smiley-4.png"/><span class="text">Robert</span></li> <li data-item="Angela"><img class="skipBaseline" src="../images/smilies/smiley-7.png"/><span class="text">Angela</span></li> </ul>
Want to continue the tour?
- Quick Links:
- Website
- GitHub
- Report an issue
- Return to top
VM UI Framework is created, owned, maintained by Virtuosi Media, Inc. © 2012-2013.