How to use the Feathers AutoComplete component

The AutoComplete class extends the TextInput component to add a pop-up list of suggestions as you type.

The Basics

First, let's create an AutoComplete control and add it to the display list:

var input:AutoComplete = new AutoComplete();
this.addChild( input );

At this point, the AutoComplete will behave like a normal TextInput without suggestions. All properties available to a TextInput (like maxChars or prompt, for example) may be used with an AutoComplete too.

Providing suggestions for completion

An IAutoCompleteSource implementation should be passed to the source property to display suggestions for completion. Let's look at a couple of the classes that we can use to provide these suggestions.

LocalAutoCompleteSource

The simplest option involves passing a ListCollection to LocalAutoCompleteSource. As the user types, the collection will be filtered to display appropriate suggestions.

input.source = new LocalAutoCompleteSource( new ListCollection(new <String>
[
    "Apple",
    "Banana",
    "Cherry",
    "Grape",
    "Lemon",
    "Orange",
    "Watermelon"
]));

When one types "ap" into the AutoComplete, the list of suggestions will include "Apple" and "Grape". By default, LocalAutoCompleteSource converts each item to lowercase, and it returns any item that contains the entered text. The entered text may be in the middle of an item, as we see when "ap" matches "Grape".

If the default behavior doesn't quite fit our needs, we can use a custom compareFunction to handle the filtering. In the following example, we create a compareFunction where the entered text must be at the very beginning of the suggestion:

var source:LocalAutoCompleteSource = new LocalAutoCompleteSource();
source.compareFunction = function( item:Object, textToMatch:String ):Boolean
{
    return item.toString().toLowerCase().indexOf(textToMatch.toLowerCase()) == 0;
};

In this case, if one types "ap" using the same data provider as in the previous example, only "Apple" will be suggested. "Grape" will not be suggested because "ap" appears in the middle of the word instead of the beginning.

As you can see above, the first argument to the compareFunction is typed as Object, meaning that suggestions don't necessarily need to be strings.

URLAutoCompleteSource

In some cases, you may want to request personalized suggestions from a server instead. We can pass the text entered by the user to a backend API using URLAutoCompleteSource.

To load suggestions from the web, we need a URL. The urlRequestFunction property can be used to generate a URLRequest:

var source:URLAutoCompleteSource = new URLAutoCompleteSource();
source.urlRequestFunction = function( textToMatch:String ):URLRequest
{
    var request:URLRequest = new URLRequest( "http://example.com/search_suggestions" );
    var variables:URLVariables = new URLVariables();
    variables.query = textToMatch;
    request.data = variables;
    return request;
};
input.source = source;

The urlRequestFunction takes one argument, the text entered into the AutoComplete. We can pass that to the server to return relevant suggestions.

By default, URLAutoCompleteSource parses the result as a JSON array. If the result returned by the API looks similar to the example below, it can be parsed automatically:

[
    "adobe",
    "adobe flash",
    "adobe reader",
    "adobe creative cloud"
]

However, if the API returns data in a different format, we can use the parseResultFunction property to tell the URLAutoCompleteSource how to convert the result into something that the pop-up list of suggestions can display.

Let's create a parseResultFunction for some XML in the following format:

<search>
    <suggestion>adobe</suggestion>
    <suggestion>adobe flash</suggestion>
    <suggestion>adobe reader</suggestion>
    <suggestion>adobe creative cloud</suggestion>
</search>

In the custom parseResultFunction below, we loop through each <suggestion> element in the result and extract the string. We'll return an Array of these strings:

source.parseResultFunction = function( result:String ):Object
{
    var parsedSuggestions:Array = [];
    var xmlResult:XML = new XML( result );
    var resultCount:int = xmlResult.suggestion.length();
    for( var i:int = 0; i < resultCount; i++ )
    {
        var suggestion:XML = xmlResult.suggestion[i];
        parsedSuggestions.push( suggestion.toString() );
    }
    return parsedSuggestions;
};

The parseResultFunction may return any type of object that may be passed to a ListCollection, such as an Array or a Vector.

Customizing suggestion behavior

The minimumAutoCompleteLength property determines how many characters must be entered into the input before displaying suggestions:

input.minimumAutoCompleteLength = 3;

By default, the input will not make suggestions until at least 2 characters have been typed.

The autoCompleteDelay property determines how long to wait after the text in the input has been edited before updating the suggestions:

input.autoCompleteDelay = 0.25;

This value is measured in seconds, and the default value is 0.5.

Skinning an AutoComplete

An AutoComplete provides a number of properties to customize its appearance. For full details about what skin and style properties are available, see the AutoComplete API reference.

As mentioned above, AutoComplete is a subclass of TextInput. For more detailed information about the skinning options available to AutoComplete, see How to use the Feathers TextInput component.

Targeting an AutoComplete in a theme

If you are creating a theme, you can set a function for the default styles like this:

getStyleProviderForClass( AutoComplete ).defaultStyleFunction = setAutoCompleteStyles;

If you want to customize a specific AutoComplete to look different than the default, you may use a custom style name to call a different function:

input.styleNameList.add( "custom-auto-complete" );

You can set the function for the custom style name like this:

getStyleProviderForClass( AutoComplete )
    .setFunctionForStyleName( "custom-auto-complete", setCustomAutoCompleteStyles );

Trying to change the auto complete's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the AutoComplete was added to the stage and initialized. Learn to extend an existing theme to add custom skins.

If you aren't using a theme, then you may set any of the auto complete's properties directly.