index.mustache revision 7c8b9c34abc116bbaed3f048d8e141ac5c46a366
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<div class="intro">
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<img src="assets/img/autocomplete-01.png" alt="Screenshot of the AutoComplete list widget" style="border: 1px solid #bfbfbf; float:right; height:161px; margin: 0 0 8px 8px; width:272px;">
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe AutoComplete widget provides a flexible, configurable, and accessible implementation of the <a href="http://developer.yahoo.com/ypatterns/selection/autocomplete.html">AutoComplete design pattern</a>, which offers suggestions or provides some other form of filtering or completion as a user types text in an input field.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwIn addition to the core logic for filtering and completion, AutoComplete also provides options for custom filtering, highlighting, and formatting of results; delimited queries; result retrieval from a variety of local and remote sources including <a href="http://developer.yahoo.com/yql/">YQL</a>, JSONP, and XHR; and more.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwAutoComplete is also built to be modular and easy to extend so that it can be used as the basis for custom implementations and widgets.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw{{>getting-started}}
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h2>Using AutoComplete</h2>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h3>Quick Start</h3>
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United StatesIn a hurry? Here's how to get up and running with AutoComplete in just a few lines of code. The following examples demonstrate how to use AutoComplete with several common result sources. Pick the one that most closely matches your needs (you only need one!).
8d7e41661dc4633488e93b13363137523ce59977jose borregoYUI().use('autocomplete', 'autocomplete-highlighters', function (Y) {
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // Add the yui3-skin-sam class to the body so the default
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // AutoComplete widget skin will be applied.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw Y.one('body').addClass('yui3-skin-sam');
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // The following examples demonstrate some of the different
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // result sources AutoComplete supports. You only need to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // pick one, you don't need them all. Assume the '#ac-input'
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // element id used in this example refers to an <input>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // element on the page.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // Array source. Replace the example array with any array.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as resultHighlighter: 'phraseMatch',
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as source: ['foo', 'bar', 'baz']
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // YQL source. Leave the {query} placeholder as is; AutoComplete
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw // will replace it automatically.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw resultHighlighter: 'phraseMatch',
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb source: 'select * from search.suggest where query="{query}"'
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright // JSONP URL source. Leave the {query} and {callback} placeholders
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright // as is; AutoComplete will replace them automatically.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Y.one('#ac-input').plug(Y.Plugin.AutoComplete, {
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright resultHighlighter: 'phraseMatch',
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright source: 'http://example.com/search.jsonp?q={query}&callback={callback}'
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright // XHR URL source (no callback). Leave the {query} placeholder
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright // as is; AutoComplete will replace it automatically.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Y.one('#ac-input').plug(Y.Plugin.AutoComplete, {
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright resultHighlighter: 'phraseMatch',
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States source: 'http://example.com/search.json?q={query}'
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States });
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States});
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States```
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwIn most cases, one of these examples should be enough to get you started. For a more complete discussion of how to use, configure, and customize AutoComplete, read on.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h3>Instantiating AutoComplete</h3>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asThere are two ways to instantiate an AutoComplete widget: you can plug `Y.Plugin.AutoComplete` into an existing `Y.Node` instance, or you can create a new standalone instance of the `Y.AutoComplete` class.
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States</p>
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States<p>
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United StatesBoth instantiation methods provide the same AutoComplete functionality, so feel free to use whichever one you prefer. Throughout this guide and in the examples, the plugin method is used most, but the class method will work equally well in all cases.
eb1d736b1c19f6abeee90c921a9320b67fedd016afshin salek ardakani - Sun Microsystems - Irvine United States</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwWhichever instantiation method you choose, be sure to add the `yui3-skin-sam` classname to the page's `<body>` element or to a parent element of the AutoComplete widget in order to apply the default CSS skin:
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as<body class="yui3-skin-sam">
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asSee the [[#Skinning]] section below for more info.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as<h4>As a Plugin</h4>
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United StatesTo instantiate AutoComplete as a plugin, use the `plug()` method to attach it to an existing `Y.Node` instance. The node must be an `<input>` or `<textarea>` element. You may also provide a configuration object containing AutoComplete config attributes, but this isn't required.
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United StatesY.one('#ac-input').plug(Y.Plugin.AutoComplete);
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwIn most cases, you'll at least want to specify a `source` attribute, which tells AutoComplete where to get results. The simplest type of source is an array of strings.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw source: ['friends', 'Romans', 'countrymen']
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwOnce you've plugged AutoComplete into a node, you can access the AutoComplete instance through the node's `ac` property.
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States```
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwvar inputNode = Y.one('#ac-input');
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwinputNode.ac.set('source', ['friends', 'Romans', 'countrymen']);
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwWhen using AutoComplete as a plugin, the AutoComplete widget markup will be rendered automatically as soon as it's plugged into a node instance. If you'd like to defer rendering until a time of your choosing, set the `render` config attribute to `false`.
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United States// Don't render immediately.
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United StatesY.one('#ac-input').plug(Y.Plugin.AutoComplete, {render: false});
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United States// Render only when I say so.
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United StatesY.one('#ac-input').ac.render();
b89a8333f5e1f75ec0c269b22524bd2eccb972banatalie li - Sun Microsystems - Irvine United StatesBy default, the AutoComplete widget markup is appended to the parent node of the node it's plugged into. If you would rather render the markup inside a different parent, pass a CSS selector or `Y.Node` instance to the `render` config attribute or the `render()` method.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw// Render inside the #ac-parent node.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwY.one('#ac-input').plug(Y.Plugin.AutoComplete, {render: '#ac-parent'});
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwFor more on available configuration attributes, see the [[#Configuring AutoComplete]] section below. For more on the different result sources AutoComplete supports, see [[#Result Sources]].
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h4>As a Class</h4>
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwTo instantiate AutoComplete as a class, create a new instance of `Y.AutoComplete` and specify an `inputNode` config value. The `inputNode` must be a CSS selector, `Y.Node` instance, or DOM element referencing an `<input>` or `<textarea>` element that already exists on the page.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwvar ac = new Y.AutoComplete({inputNode: '#ac-input'});
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw`inputNode` is the only required configuration attribute, but in most cases you'll also want to specify a `source` attribute, which tells AutoComplete where to get results. The simplest type of source is an array of strings.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwvar ac = new Y.AutoComplete({
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw inputNode: '#ac-input',
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw source : ['friends', 'Romans', 'countrymen']
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States```
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<p>
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United StatesWhen instantiated as a class, the AutoComplete widget markup is not rendered automatically. To render it, either set the `render` config attribute to `true` at instantiation time or call the AutoComplete instance's `render()` method later.
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States</p>
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States// Render immediately.
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United Statesvar ac = new Y.AutoComplete({
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States inputNode: '#ac-input',
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States render : true
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States});
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw// Don't render immediately.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwvar ac = new Y.AutoComplete({inputNode: '#ac-input'});
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw// Render only when I say so.
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States```
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States<p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwBy default, the AutoComplete widget markup is appended to the parent node of the `inputNode` when the widget is rendered. If you would rather render the markup inside a different parent, pass a CSS selector or `Y.Node` instance to the `render` config attribute or the `render()` method.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as// Render inside the #ac-parent node.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asvar ac = new Y.AutoComplete({inputNode: '#ac-input'});
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwac.render('#ac-parent');
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United StatesFor more on available configuration attributes, see the [[#Configuring AutoComplete]] section below. For more on the different result sources AutoComplete supports, see [[#Result sources]].
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States</p>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h3>DOM Structure</h3>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asWhen the AutoComplete widget is rendered, it will add the CSS class `yui3-aclist-input` to the specified `inputNode`, along with several ARIA attributes.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as<!-- Before AutoComplete is rendered -->
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as<input id="ac-input" type="text">
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<!-- After AutoComplete is rendered -->
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<input id="ac-input" type="text" class="yui3-aclist-input"
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as aria-autocomplete="list" aria-expanded="false"
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as aria-owns="yui_3_3_0_1_129140941365181" role="combobox"
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as autocomplete="off">
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asAutoComplete will also add markup for the list widget. By default, the list markup will be appended to the parent node that contains the `inputNode`.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<!-- AutoCompleteList widget markup with sample results -->
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<div id="yui_3_3_0_1_129140941365147"
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as class="yui3-widget yui3-aclist yui3-widget-positioned yui3-widget-stacked yui3-aclist-hidden"
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw style="z-index: 0; width: 254px; left: 13px; top: 32px; "
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as aria-hidden="true">
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <div id="yui_3_3_0_1_129140941365150" class="yui3-aclist-content">
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <ul class="yui3-aclist-list" id="yui_3_3_0_1_129140941365181" role="listbox">
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <li class="yui3-aclist-item" id="yui_3_3_0_1_1291409413651452" role="option">friends</li>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <li class="yui3-aclist-item" id="yui_3_3_0_1_1291409413651454" role="option">Romans</li>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <li class="yui3-aclist-item" id="yui_3_3_0_1_1291409413651456" role="option">countrymen</li>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asFor information on skinning the AutoComplete widget, see the [[#Skinning]] section below.
8d7e41661dc4633488e93b13363137523ce59977jose borrego<h3>Configuring AutoComplete</h3>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asExcept for `inputNode`, all configuration attributes are optional. These lists only contain the most interesting attributes. For a complete list of all attributes, please refer to the <a href="/yui/3/api/module_autocomplete.html">API docs</a>.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as<h4>Base Config Attributes</h4>
8d7e41661dc4633488e93b13363137523ce59977jose borregoThese attributes are provided by `AutoCompleteBase`, which is the core foundation for the AutoComplete widget. They are available on all AutoComplete instances.
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <th>Attribute</th>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <th>Default</th>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <th>Description</th>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <td>`allowBrowserAutocomplete`</td>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <td>`false`</td>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as Whether or not to enable the browser's built-in autocomplete functionality for input fields.
8d7e41661dc4633488e93b13363137523ce59977jose borrego <td>`inputNode`</td>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <td><em>none</em></td>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <strong>Required</strong>. `<input>` or `<textarea>` node to monitor for changes.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <td>`maxResults`</td>
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as <td>0</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb Maximum number of results to display. A value of `0` or less will allow an unlimited number of results.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`minQueryLength`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>1</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb Minimum number of characters that must be entered before a `query` event will be fired. A value of `0` allows empty queries; a negative value will effectively disable all `query` events and turn AutoComplete off.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`queryDelay`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>100</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb Number of milliseconds to wait after user input before triggering a `query` event. If new input occurs before this delay is over, the previous input event will be ignored and a new delay will begin.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb This is useful to throttle queries to a remote data source, and to avoid distracting the user by showing them less relevant results before their typing pauses.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`queryDelimiter`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Query delimiter string. When a delimiter is configured, the input value will be split on the delimiter, and only the last portion will be used in autocomplete queries and updated when the `query` attribute is modified. See [[#Using Query Delimiters]] below for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`requestTemplate`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Source request template. This can be a function that accepts a query as a parameter and returns a string, or it can be a string containing the placeholder "{query}", which will be replaced with the URI-encoded query. The resulting string will be appended to the request URL when the `source` attribute is set to a remote DataSource, JSONP URL, or XHR URL.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`resultFilters`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`[]`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Result filter name, function, or array of filter names and/or functions. See [[#Filtering Results]] for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`resultFormatter`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Function that should be used to format results. See [[#Writing Result Formatters]] for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`resultHighlighter`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Result highlighter name or function. See [[#Highlighting Results]] for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`resultListLocator`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Locator string or function that should be used to extract an array of results from a non-array response. See [[#Locating Results]] for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`resultTextLocator`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Locator string or function that should be used to extract a plain text string from a non-string result item. See [[#Locating Results]] for details.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`source`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`null`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Source for autocomplete results. The following source types are supported: Array, DataSource, Function, Object, JSONP URL (string), XHR URL (string), YQL query (string). For details on each source type, see [[#Result Sources]].
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright<h4>List Config Attributes</h4>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan WrightThese attributes are provided by `AutoCompleteList`, which is the implementation for the AutoComplete list widget. They are available on all instances of `AutoComplete` or `AutoCompleteList`, as well as on instances of the AutoComplete plugin.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <th>Attribute</th>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <th>Default</th>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <th>Description</th>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`activateFirstItem`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`false`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright If `true`, the first item in the result list will be activated by default when the list is initially displayed and when results change.
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright <td>`align`</td>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright node: <em>inputNode</em>,
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright points: ['tl', 'bl']
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright}</code></pre>
a0aa776e20803c84edd153d9cb584fd67163aef3Alan Wright Widget alignment config. The `node` property is the element with which the result list should be aligned, and the `points` property specifies (by default) that the top left of the list should be aligned with the bottom left of the `inputNode`.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`alwaysShowList`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`false`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb If `true`, the list will remain visible even when there are no results to display and the `inputNode` is not focused.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`circular`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`true`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb If `true`, keyboard navigation will wrap around to the opposite end of the list when navigating past the first or last item.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`scrollIntoView`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`false`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb If `true`, the viewport will be scrolled when necessary to ensure that the active list item is visible.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`tabSelect`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb <td>`true`</td>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb If `true`, pressing the tab key while the list is visible will select the active item, if any.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb<h4>Aligning the List</h4>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbBy default, the autocomplete dropdown list will be automatically aligned with the bottom left corner of the input node it's attached to, and its width will be set to match the input node's. You can change the alignment of the list by specifying a custom value for the `align` attribute.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbFor example, to align the top left of the list with the top left of a particular node on the page (such as its container):
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb node : '#container',
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb points: ['tl', 'tl']
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbSee the <a href="/yui/3/api/WidgetPositionAlign.html">WidgetPositionAlign API docs</a> for more details on alignment configs.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb<h4>Using Query Delimiters</h4>
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbUsing the `queryDelimiter` attribute, you can specify a delimiter string that should be used to split the value of the input field.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbWhen a delimiter is set, the `query` attribute will only reflect the last delimited item in the input value, and only this item will be used for completion (the full input value will still be available from the `value` attribute).
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbFor example, if `queryDelimiter` is set to `','` and the input node's value is `'foo, bar, baz'`, then the value of the `query` attribute will be `'baz'`.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbvar inputNode = Y.one('#ac-input');
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbinputNode.set('value', 'foo, bar, baz');
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb queryDelimiter: ','
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwWhen the user selects an item from the result list, the selected item will replace only the last delimited item in the input value rather than replacing the entire value, and another delimiter string will be automatically appended to the value so that the user can continue typing and getting suggestions.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h3>AutoComplete Events</h3>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThese lists only contain the most interesting events. For a complete list, please refer to the <a href="/yui/3/api/module_autocomplete.html">API docs</a>.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw<h4>Base Events</h4>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThese events are provided by `AutoCompleteBase`, which is the core foundation for the AutoComplete widget. They are available on all AutoComplete instances.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <th>Event</th>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <th>When</th>
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw <th>Payload</th>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <td>`clear`</td>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb The query has been completely cleared or no longer meets the minimum query length requirement.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <dt>`prevVal` <i>(String)</i></dt>
bbf6f00c25b6a2bed23c35eac6d62998ecdb338cJordan Brown Value of the query before it was cleared.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <td>`query`</td>
bbf6f00c25b6a2bed23c35eac6d62998ecdb338cJordan Brown The value of the input field has changed and the new value meets the criteria necessary to generate an autocomplete query. Can be prevented to stop the query from being sent.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <dt>`inputValue` <i>(String)</i></dt>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb Full contents of the text input field or textarea that generated the query.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <dt>`query` <i>(String)</i></dt>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb The query itself. This is the string that will be sent to the result source to request results. It may or may not be the same as `inputValue`.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <td>`results`</td>
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego Results are received from the result source. If no source has been set, this event will not fire.
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <dt>`data` <i>(Array|Object)</i></dt>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb Raw, unfiltered result data from the source (if available).
7b59d02d2a384be9a08087b14defadd214b3c1ddjb <dt>`query` <i>(String)</i></dt>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb Query that generated these results.
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego <dt>`results` <i>(Array)</i></dt>
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego Array of filtered, formatted, and highlighted results. Each item in the array is an object with the following properties:
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego <dt>`display` <i>(Node|HTMLElement|String)</i></dt>
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego Formatted result HTML suitable for display to the user. If no custom formatter is set, this will be an HTML-escaped version of the string in the `text` property.
7f667e74610492ddbce8ce60f52ece95d2401949jose borrego <dt>`highlighted` <i>(String)</i></dt>
7b59d02d2a384be9a08087b14defadd214b3c1ddjb Highlighted (but not formatted) result text. This property will
7b59d02d2a384be9a08087b14defadd214b3c1ddjb only be set if a highlighter is in use.
29bd28862cfb8abbd3a0f0a4b17e08bbc3652836Alan Wright <dt>`raw` <i>(mixed)</i></dt>
8d7e41661dc4633488e93b13363137523ce59977jose borrego Raw, unformatted result in whatever form it was provided by the
8d7e41661dc4633488e93b13363137523ce59977jose borrego <dt>`text` <i>(String)</i></dt>
8d7e41661dc4633488e93b13363137523ce59977jose borrego Plain text version of the result, suitable for being inserted
8d7e41661dc4633488e93b13363137523ce59977jose borrego into the value of a text input field or textarea when the result
8d7e41661dc4633488e93b13363137523ce59977jose borrego is selected by a user. This value is not HTML-escaped and should
8d7e41661dc4633488e93b13363137523ce59977jose borrego not be inserted into the page using innerHTML.
8d7e41661dc4633488e93b13363137523ce59977jose borrego<h4>List Events</h4>
8d7e41661dc4633488e93b13363137523ce59977jose borregoThese events are provided by `AutoCompleteList`, which is the implementation for the AutoComplete list widget. They are available on all instances of `AutoComplete` or `AutoCompleteList`, as well as on instances of the AutoComplete plugin.
8d7e41661dc4633488e93b13363137523ce59977jose borrego <th>Event</th>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <th>When</th>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <th>Payload</th>
8d7e41661dc4633488e93b13363137523ce59977jose borrego <td>`activeItemChange`</td>
8d7e41661dc4633488e93b13363137523ce59977jose borrego The active list item (the item currently pre-selected via the keyboard) changes. When the user presses enter, this is the item that will become selected.
8d7e41661dc4633488e93b13363137523ce59977jose borrego <dt>`prevVal` <i>(Node|null)</i></dt>
Result object for the selected result. See the docs for the `results` event for a description of the result object structure.
<h4>Array/Object</h4>
Set the `source` attribute to an Array to use that array as the set of results for all queries. Combine this with one or more result filters to filter out results that aren't relevant for the current query.
You can also set `source` to an Object. When the query matches one of the properties on the object, the value of that property will be used as the results for the query.
Any <a href="../datasource/">YUI DataSource</a> instance may be used as a result source. This is useful if you want to share data between multiple components on a page, or if you need to parse data or apply a DataSchema in a way that isn't feasible with other AutoComplete sources.
var ds = new Y.DataSource.IO({
source: 'http://example.com/search'
In this example, the `requestTemplate` attribute is set to a string containing a `{query}` placeholder. On each query, the placeholder will be replaced with the URI-encoded query value, and the resulting request string will be appended to the DataSource's source URL, resulting in a final URL like `http://example.com/search?q=foo`.
Set the `source` attribute to a function to use that function as the result source. On each query, the function will be called with the query as an argument. It should return an array of results.
// ...arbitrary logic here...
<h4>JSONP/XHR URL</h4>
The URL string must include a `{query}` placeholder. On each query, AutoComplete will replace this with the current query and will make a request to the URL.
If the URL string includes a `{callback}` placeholder, it will be called using JSONP, and the `{callback}` placeholder will be replaced with the name of a dynamically generated JSONP callback function that AutoComplete will create. The server is expected to respond with a JavaScript value wrapped in a call to this callback function.
If the URL string does not include a `{callback}` placeholder, it will be called using XHR (XMLHttpRequest). XHR URLs <em>must</em> abide by the <a href="https://developer.mozilla.org/en/Same_origin_policy_for_JavaScript">same origin policy</a> or the browser will refuse to send the request. The server is expected to respond with valid JSON data, which AutoComplete will attempt to parse.
source: 'http://example.com/search.jsonp?q={query}&callback={callback}'
source: 'http://example.com/search.json?q={query}'
You may also optionally include a `{maxResults}` placeholder in the URL, which will be replaced with the value of the `maxResults` attribute (or 1000 if the `maxResults` attribute is less than or equal to 0).
Responses from JSONP and XHR URL sources are automatically cached based on the query value for the duration of the pageview on a per-instance basis (in other words, every AutoComplete instance has its own separate cache).
Set the `source` attribute to a <a href="http://developer.yahoo.com/yql/">YQL</a> query string to use that YQL query as the result source.
The string must include a `{query}` placeholder. On each query, AutoComplete will replace this with the current query and will make a call to YQL to get results.
source: 'select * from search.suggest where query="{query}"'
You may also optionally include a `{maxResults}` placeholder in the YQL query, which will be replaced with the value of the `maxResults` attribute (or 1000 if the `maxResults` attribute is less than or equal to 0).
AutoComplete does its best to automatically parse results out of YQL responses, but a wide variety of different YQL response formats are possible, so it may not always be possible for AutoComplete to guess the correct format. If you find that results aren't being parsed correctly, you may need to specify a custom `resultListLocator` and/or `resultTextLocator` as described in [[#Locating Results]].
It's not uncommon for a result source to return results inside a larger data structure, such as an object that contains other metadata about the response alongside the results.
While AutoComplete automatically knows how to handle results that come back as a simple array, it needs some extra information in order to find a result array that's buried inside an object hierarchy. That's where the `resultListLocator` config attribute comes in.
resultListLocator: 'data.results',
source: 'http://example.com/search.jsonp?q={query}&callback={callback}'
In the example above, the `resultListLocator` tells AutoComplete to look for a `data` property on the response object, followed by a `results` sub-property that contains an array of results. The hierarchy may be arbitrarily deep, as long as it's consistent across responses.
If the response format isn't always the same, you can specify a function as the `resultListLocator` and run your own arbitrary logic to find (or construct) the result array. The function will receive the raw response as an argument, and must return an array of results.
source: 'http://example.com/search.jsonp?q={query}&callback={callback}'
Not all results are simple strings. Sometimes a result is an object containing lots of metadata, only part of which is a text string. In cases like this, AutoComplete needs to know how to find some text that it can display in the result list, use for highlighting, and insert into the input field when the user selects a result.
In the following sample, which is a subset of the data you might see in a response from the <a href="http://dev.twitter.com/doc/get/search">Twitter Search API</a>, an array of tweet objects is returned.
"profile_image_url": "http://a3.twimg.com/profile_images/994441119/ryan-profile-big_normal.jpg"
The `resultTextLocator` config attribute can be used to tell AutoComplete how to find some text within an individual result object, much like the `resultListLocator` attribute tells AutoComplete how to find an array of results within a response object.
source: 'http://search.twitter.com/search.json?q={query}&callback={callback}'
This tells AutoComplete that the value of each result object's `text` property should be used whenever a plain text form of the result is needed.
The `resultTextLocator` can also be a function, which allows you to perform additional logic, such as combining multiple values into a single text string. The function will receive a single result object as an argument, and must return a text string. It will be called once for each result in the results array.
source: 'http://search.twitter.com/search.json?q={query}&callback={callback}'
After results are retrieved from a result source, it may be necessary to perform additional filtering to whittle down the result list to match the query, especially if the result source doesn't perform filtering itself. The `resultFilters` attribute can be used to specify a filter or array of filters for this purpose.
A result filter is simply a function that accepts the current query and an array of result objects as arguments, and returns a filtered array of result objects.
The `autocomplete-filters` module provides a prepackaged collection of result filters. This module isn't loaded by default in the `autocomplete` rollup, but can be loaded manually as needed.
Returns results that contain all of the individual characters in the query, in any order (not necessarily consecutive).
Returns results that contain all the individual words in the query, in any order (not necessarily consecutive).
By default, all filters are case-insensitive. Case-sensitive versions are available, and can be used by appending `Case` to the filter name. For example, the case-sensitive version of the `phraseMatch` filter is `phraseMatchCase`.
In addition to the standard set of filters, the optional `autocomplete-filters-accentfold` module provides a set of filters that perform accent-folded matching.
Accent folding is when a character like `é` is converted to a non-accented form like `e`. This can be useful for performing loose matching (such as matching the word "résumé" when the query "resume" is typed), but also has some important caveats you should be aware of. See the [[#Known Issues]] section below for details.
To use accent folding filters, include the `autocomplete-filters-accentfold` module, then specify a filter by appending `Fold` to the name. For example, the accent folding version of the `phraseMatch` filter is `phraseMatchFold`. Note that all accent folding filters are case-insensitive.
After results are retrieved and (optionally) filtered, you may want to highlight occurrences of the query within each result in order to indicate to the user why that result is relevant to what they typed. The `resultHighlighter` attribute can be used to specify a result highlighter for this purpose.
Like a result filter, a highlighter is simply a function that accepts the current query and an array of result objects as arguments. Whereas filters return a filtered array of result objects, highlighters return an array of HTML strings which will be used when results are displayed to the user.
The `autocomplete-highlighters` module provides a prepackaged collection of result highlighters. This module isn't loaded by default in the `autocomplete` rollup, but can be loaded manually as needed.
Highlights individual query characters that occur anywhere in the result, in any order (not necessarily consecutive).
Highlights individual words in the result that are also in the query, in any order (not necessarily consecutive). Non-word characters like punctuation are ignored.
The prepackaged highlighters use a `<b>` element with the class `yui3-highlight` to highlight results. You can style the highlighting using CSS by referring to that class name.
By default, all highlighters are case-insensitive. Case-sensitive versions are available, and can be used by appending `Case` to the highlighter name. For example, the case-sensitive version of the `phraseMatch` highlighter is `phraseMatchCase`.
In addition to the standard set of highlighters, the optional `autocomplete-highlighters-accentfold` module provides a set of highlighters that perform accent-folded highlighting.
To use accent folding highlighters, include the `autocomplete-highlighters-accentfold` module, then specifiy a highlighter by appending `Fold` to the name. For example, the accent folding version of the `phraseMatch` highlighter is `phraseMatchFold`. Note that all accent folding highlighters are case-insensitive.
When using accent folding highlighters, there are some important caveats you should be aware of. See the [[#Known Issues]] section below for details.
AutoComplete uses the following CSS classes to provide skinning hooks for its markup. See the [[#DOM Structure]] for an example of the markup generated by the AutoComplete widget.
You can add your own CSS to override the styling of these classes and customize the display and layout of the AutoComplete widget.
ARIA live region container used to announce list updates to users of assistive tools. Positioned offscreen by default to make it invisible to sighted users.
The `contentBox` node that contains the AutoComplete list widget content. Apply visual styling like borders, padding, and margins to this node rather than the `boundingBox`.
Class added to elements that should be hidden from both sighted and unsighted users, such as when the AutoComplete list is hidden.
The `inputNode`. This node must already exist on the page and will not be created by AutoComplete, but AutoComplete will add the class name to make it consistently skinnable.
As described in [[#Filtering Results]], a result filter is just a function that accepts the current query and an array of result objects as arguments, and returns a filtered array of result objects.
query = query.toLowerCase();
return Y.Array.filter(results, function (result) {
return result.text.toLowerCase().indexOf(query) !== -1;
A result highlighter is similar to a result filter, but instead of returning a filtered array of results, it returns an array of HTML strings.
// Uses Y.Highlight, which is provided by the 'highlight' module.
return Y.Array.map(results, function (result) {
A result formatter is a function that receives the current query and an array of result objects as arguments, and must return an array of HTML strings or Node instances. Formatters run after filters and highlighters, and their output will be used for the display of result items in the final list of results.
An array of result objects created from a Twitter Search API response would look something like this after filtering and highlighting:
"profile_image_url": "http://a3.twimg.com/profile_images/994441119/ryan-profile-big_normal.jpg"
Using a result formatter, we can format these results as tweets in the result list instead of just displaying them as boring text.
return Y.Array.map(results, function (result) {
var tweet = result.raw;
return Y.Lang.sub(tweetTemplate, {
created_at : tweet.created_at,
from_user : tweet.from_user,
highlighted : result.highlighted,
profile_image_url: tweet.profile_image_url
source: 'http://search.twitter.com/search.json?q={query}&callback={callback}'
The `Y.AutoCompleteBase` class provides the core logic for a generic implementation of the autocomplete pattern, but without any UI-related functionality or implementation code. It's meant to be used as a `Y.Base` or `Y.Widget` extension and mixed into another class that builds an implementation on top of it (this is what `Y.AutoCompleteList` does).
You can take advantage of `AutoCompleteBase` to build a customized implementation of the autocomplete pattern that doesn't necessarily have to use a traditional list-based suggestion UI.
The following skeleton demonstrates how to create a standalone class that mixes in the `AutoCompleteBase` extension, making it instantiable and usable as an API, but without any user-visible interface.
From an interaction standpoint, this is a little like using AutoComplete as a blank slate. It will allow you to attach AutoComplete to an input node and hook into AutoComplete's API and events so you get result retrieval, filtering, highlighting, formatting, etc., but anything beyond that is up to you.
Building your own widget on top of `AutoCompleteBase` is easy. Just mix `AutoCompleteBase` into your widget class, then flesh it out with your own custom widget implementation. Your widget will inherit all of `AutoCompleteBase`'s methods, attributes, and events.
AutoComplete is designed to be accessible out of the box to users of screen readers and other assistive tools. This is accomplished via a combination of progressive enhancement and adherence to <a href="http://www.w3.org/WAI/intro/aria">WAI-ARIA</a> best practices, which help to convey the meaning and behavior of the AutoComplete widget to users who may not be able to see or interact with it in a conventional way.
Activates the next item in the list, or displays the list if the list is currently hidden. Wraps around to the top of the list if the `circular` config attribute is set to `true` and there is no next item.
When the list is visible and an item is active, selects the currently active item and hides the list.
When the list is visible and an item is active, selects the currently active item and hides the list.
Activates the previous item in the list. Wraps around to the bottom of the list if the `circular` config attribute is set to `true` and there is no previous item.
Keyboard functionality is not loaded by default for users of iOS and Android-based devices, since these devices typically don't provide support for keyboard interaction. If for some reason you want to load the keyboard code for these devices, include the `autocomplete-list-keys` module in your `YUI().use()` statement.
Indicates that the specified result item node is the active (pre-selected) item in the list owned by this `inputNode`. This attribute is added or removed automatically when the `activeItem` changes.
Indicates that the `inputNode` provides autocomplete suggestions in the form of a list as the user types.
Indicates whether the result list is expanded (true) or collapsed (false). This attribute will be updated automatically when the list's state changes.
Indicates that there is a parent/child relationship between the `inputNode` (which accepts user input) and the `listNode` (which displays autocomplete results related to that input).
Not all assistive tools support the `aria-owns` attribute. For this reason, it's strongly recommended that you allow the AutoComplete widget to render its list markup inside the same container element as the input node, and immediately after the input node (this is the default behavior) rather than specifying a different parent node.
Indicates that the `inputNode` represents the combination of an editable text field with a popup list.
Applied to the `boundingBox`. Indicates whether the result list is hidden (true) or visible (false). This attribute will be updated automatically when the lists's state changes.
Applied to the `listNode`. Indicates that this node represents a widget that allows the user to select one or more items from a list of choices.
Applied to individual result item nodes inside the `listNode`. Indicates that the node represents a selectable item in a list.
The accent folding implementation used for filters and highlighters is not comprehensive, since it wouldn't be practical to serve a complete set of character data to clients via JS. The implementation used here provides basic accent folding for common alphanumeric characters only, and is not locale-aware. Whenever possible, accent folding should be done on the server, where more complete character data can be used, and not on the client.
When used for matching, accent folding is likely to produce erroneous matches for languages in which characters with diacritics are considered different from their base characters, or where correct folding would map to other character sequences than just stripped characters.
For example, in German "ü" is a character that's clearly different from "u" and should match "ue" instead. The word "betrügen" means "to defraud", while "betrugen" is the past tense of "to behave". The name "Müller" is expected to match "Mueller", but not "Muller".
On the other hand, accent folding falls short for languages where different base characters are expected to match. In Japanese, for example, hiragana and katakana characters with the same pronunciation ("あ" and "ア") are commonly treated as equivalent for lookups, but accent folding treats them as different.
The result highlighters provided by the `autocomplete-highlighters` module may introduce unwanted word breaks in Arabic, Syriac, and N'Ko scripts. This issue is being tracked in <a href="http://yuilibrary.com/projects/yui3/ticket/2529396">ticket #2529396</a>, and will be fixed in a future release.