NativeScript Core

RadAutoCompleteTextView Getting Started

In this article, you will learn how to initialize RadAutoCompleteTextView and use it with its basic configuration.

Installation

RadAutoCompleteTextView is distributed through the nativescript-ui-autocomplete package, so before using it, you need to run the following command to add the plugin to your application:

tns plugin add nativescript-ui-autocomplete

Initialization

Then, in order to add a RadAutoCompleteTextView instance in a page of your application, you need to define the following XML namespace:

  • xmlns:au="nativescript-ui-autocomplete"

To create a RadAutoCompleteTextView you should use the RadAutoCompleteTextView tag in your .xml file. Once you have added the tag you should specify value for the items property of the control.

<au:RadAutoCompleteTextView id="autocomplete" items="{{ dataItems }}" displayMode="Tokens"/>

In order to provide suggestions that will be used by RadAutoCompleteTextView you need to provide a collection of items of type TokenModel:

import { ObservableArray } from "tns-core-modules/data/observable-array";
import { TokenModel } from "nativescript-ui-autocomplete";
import { Observable } from "tns-core-modules/data/observable";

export class ViewModel extends Observable {
    private countries = ["Australia", "Albania", "Austria", "Argentina", "Maldives", "Bulgaria", "Belgium", "Cyprus", "Italy", "Japan",
        "Denmark", "Finland", "France", "Germany", "Greece", "Hungary", "Ireland",
        "Latvia", "Luxembourg", "Macedonia", "Moldova", "Monaco", "Netherlands", "Norway",
        "Poland", "Romania", "Russia", "Sweden", "Slovenia", "Slovakia", "Turkey", "Ukraine",
        "Vatican City", "Chad", "China", "Chile"];

    get dataItems(): ObservableArray<TokenModel> {
        return this.get("_dataItems");
    }

    set dataItems(value: ObservableArray<TokenModel>) {
        this.set("_dataItems", value);
    }

    private initDataItems() {
        this.dataItems = new ObservableArray<TokenModel>();

        for (let i = 0; i < this.countries.length; i++) {
            this.dataItems.push(new TokenModel(this.countries[i], undefined));
        }
    }
}

If necessarily, you can also use RadAutoCompleteTextView's hint property to provide a text that will be displayed when there is no input; the text property that allows you to change the text or get the current user input or the noResultsText property to change the text displayed when no suggestions are found.

Customize the Suggestions

When you start typing the input field, you will see the default suggestion view displayed below the input field. If you want, you can add a custom suggestion view and change its template (through the suggestionItemTemplate property) and/or fix its height (through the suggestionViewHeight property). Here's an example:

<au:RadAutoCompleteTextView.suggestionView>
    <au:SuggestionView suggestionViewHeight="300">
        <au:SuggestionView.suggestionItemTemplate>
            <StackLayout orientation="vertical" padding="10">
                <Label text="{{ text }}"></Label>
            </StackLayout>
        </au:SuggestionView.suggestionItemTemplate>
    </au:SuggestionView>
</au:RadAutoCompleteTextView.suggestionView>

Customize the TokenModel

If you need, you can extend the TokenModel with an id to track more easily the selected items or any other information that you need that is missing from the default model. Here's an example:

export class CityModel extends TokenModel {
    public id: number;
    public city: string;
    public country: string;
    constructor(id: number, city: string, country: string, image: string) {
        super(city + ", " + country, image);

        this.id = id;
        this.city = city;
        this.country = country;
    }

    toString() {
        return this.id + ": " + this.city + ", " + this.country;
    }
}

Then you can use the new type to populate the list of items that will be bound to RadAutoCompleteTextView's items property:

private initDataItems() {
    if (!this.dataItems) {
        this.dataItems = new ObservableArray<CityModel>();
        for (let i = 0; i < data.items.length; i++) {
            const d = data.items[i].flag;
            const ds = "res://" + d;
            this.dataItems.push(new CityModel(data.items[i].id, data.items[i].city, data.items[i].country, ds));
        }
    }
}

You can also display the properties added to your custom model in the template of the suggestions:

<au:RadAutoCompleteTextView.suggestionView>
    <au:SuggestionView>
        <au:SuggestionView.suggestionItemTemplate>
            <GridLayout columns="auto, *">
                <Image src="{{ image }}" marginLeft="10" width="50" verticalAlignment="center"></Image>
                <Label text="{{ city }}" marginLeft="10" col="1" verticalAlignment="center"></Label>
                <Label text="{{ country }}" marginRight="10" col="1" verticalAlignment="center" textAlignment="right"></Label>
            </GridLayout>
        </au:SuggestionView.suggestionItemTemplate>
    </au:SuggestionView>
</au:RadAutoCompleteTextView.suggestionView>

Apply CSS

RadAutoCompleteTextView can be customized through CSS. You can use the following type selectors to define the styles for the different elements:

  • RadAutoCompleteTextView: Can be used to apply styles for the whole component.
  • SuggestionView: Can be used to apply styles for the SuggestionView that displays below the input field.
  • Token: Can be used to apply styles for the Tokens that get added to the input field when they are selected from the suggestions.
  • ClearButton: Can be used to apply styles for the 'X' used to clear the current input
  • TokenClearButton: Can be used to apply styles for the 'X' inside a Token, that is used to remove that Token from the input field.
  • NoResultsLabel: Can be used to apply styles for the text that is displayed when no suggestions are found for the current input.

Each of these selectors supports a subset of properties that can be applied:

  • RadAutoCompleteTextView supports: color, padding, margin, background-related properties (background, background-color, etc.), border-related properties (border-color, border-width, etc.), font-related properties (font-size, font-weight, etc.); these can also be applied for RadAutoCompleteTextView when its state is focus
  • SuggestionView supports: color, margin, background-related properties (background, background-color, etc.), border-related properties (border-color, border-width, etc.), font-related properties (font-size, font-weight, etc.)
  • Token supports: color, padding, margin, background-related properties (background, background-color, etc.), border-related properties (border-color, border-width, etc.), font-related properties (font-size, font-weight, etc.); these can also be applied for Token when its state is selected
  • ClearButton and TokenClearButton support: color and background-image. The color can be used to tint the image used by default, while background-image can be used to use a custom image.
  • NoResultsLabel supports: color and font-related properties (font-size, font-weight, etc.)

Here's an example CSS:

Example 1: Applying css to RadAutoCompleteTextView instances with class ac3

RadAutoCompleteTextView.ac3 {
margin: 5 10;
padding: 0 6;
color: #00C147;
background: white;
token-item-spacing: 12;
display-mode: tokens;
layout-mode: horizontal;
}

RadAutoCompleteTextView.ac3 Token {
color: #00C147;
background: white;
border-radius: 20;
border-color: #00C147;
border-width: 4;
font-weight: bold;
}

RadAutoCompleteTextView.ac3 Token:selected {
color: white;
background: #00C147;
}

RadAutoCompleteTextView.ac3 Token TokenClearButton {
color: #00C147;
}

RadAutoCompleteTextView.ac3 Token:selected TokenClearButton {
color: white;
}


RadAutoCompleteTextView.ac3 ClearButton {
color: #00C147;
}

And here's how RadAutoCompleteTextView looks when the above CSS is applied:

Figure 1: RadAutoCompleteTextView with applied css on Android (left) and iOS (right)

NativeScriptUI-AutoComplete-CSS-Android NativeScriptUI-AutoComplete-CSS-iOS

References

Want to see more examples using RadAutoCompleteTextView? Check our SDK examples repository on GitHub. You will find this and a lot more practical examples with NativeScript UI.