Using (and customizing) the AutoCompleteBox for Windows Phone

This is my first article on Windows Phone 7 development and I will focus on a subject that was useful in one of my recent projects: using the an autocomplete box in a Windows Phone 7 application.

By default, the Windows Phone SDK doesn’t include an AutoCompleteBox control for use, but as probably many people already know, the Silverlight Toolkit library released on CodePlex contains such a control designed for the phone.

In order to demo the usage of the AutoCompleteBox control we’ll create a very simple application which will allow us to select our favourite cities from a predefined list. I am using Microsoft Visual Studio 2010 Express for Windows Phone.

Once you downloaded the latest Windows Phone Silverlight Toolkit – November 2011 (7.1 SDK) and installed it, you will  need to add a reference to the Microsoft.Phone.Controls.Toolkit.dll assembly in your project.


To use the AutoCompleteBox control in your XAML, you will need to edit the XAML source and add the toolkit namespace as shown before:


After this step you are ready to use the AutoCompleteBox in your page. The AutoCompleteBox is a rather simple control to use, looking like a regular TextBox, but as the user starts typing into it, it displays a suggestions drop-down list based on the matches found. For the AutoCompleteBox to offer the suggestions based on what’s being typed we need to make sure that we set the ItemsSource property of the control which takes an IEnumerable collection.

For the simplest use of the AutoCompleteBox, all you have to do once you performed the steps above is to create an AutoCompleteBox control in your XAML as shown below:


and then assign the ItemsSource property to a collection (I’ve done it in code behind, but you can also use binding in your XAML):


That’s it! Now you can run your application and test it… If you would be typing the character s, you should be seeing something like this:


If you want to get the value from the AutoCompleteBox, you can check the Text property of the AutoCompleteBox control.

In a real world application it makes sense that you may want to set the Text property to some previously stored value and then allow the user to modify it if necessary.

So, after setting the ItemsSource of the AutoCompleteBox to the list of cities, add an extra line that will also set the Text property to Suceava (value that exists in our list):

cities.Text = “Suceava”;

If you run the  application again, you notice you have a problem:


The AutoCompleteBox control has the suggestions drop-down list opened… I don’t want that by default and I guess most people don’t want this behaviour as well. So let’s fix it.

We need to handle 3 simple events exposed by the AutoCompleteBox:


All the events are rather simple and their names are very clear: the GetFocus and LostFocus are triggered when the control gets and loses the focus, while the DropDownOpening event is triggered just before the opening of the suggestion drop-down allowing us to stop the suggestion if needed.

The GetFocus and LostFocus will set a boolean variable to true or false to allow us to know if the control is focused or not. In the DropDownOpening event we will use this boolean value and we will not allow the drop-down list to open if the control is not focused – just the scenario we have above. To stop the drop-down from opening we need to cancel the event. Here is the code:


Try running the application again once you implemented the events above. The application should behave as expected: the control has by default the value “Suceava” and the drop-down list is not opened by default.

What we’ve done so far is a very simple scenario of AutoCompleteBox usage. In lots of cases it could be enough, in others not.

Imagine you want to allow your users to input multiple cities in the same AutoCompleteBox control, each city separated by a comma and for each city you want to help your user by providing him help (suggestions) based on what he’s typing.

If you run the application now and type a comma after your initial selection and then start typing the first letter of another city, you will not get any suggestions as the list provided to the ItemsSource property doesn’t contain any string that will match your entire text value.

To finish this demo, we’ll try to modify the default behaviour of the AutoCompleteBox and customize it to allow us to cover the previous scenario.

To implement this, we’ll need to:

  • use one variable to remember the previously typed cities
  • handle the TextChanged and SelectionChanged events of the AutoCompleteBox. The TextChanged event has the same use as for a TextBox control, while the SelectionChangedevent is triggered when the selection in the suggestion drop-down control is changed.
  • we need also to implement a custom search method that will be used by the TextFilter property of the AutoCompleteBox

We will use the TextChanged event to store in the new variable the previous cities that the user types, in the SelectionChanged we will make sure to append the newly selected city to the previously typed cities.

The custom filtering method will make sure that we use only what is after a comma as search term. Also, this method will make sure to filter out cities that we already typed.

So, to get to the coding part, we need to attach some more events to the AutoCompleteBox:


The custom filter method is rather simple and looks like this:


The TextChanged and SelectionChanged events are also simple:


If you will run the application again you will see that the same AutoCompleteBox allows us to input multiple cities, separated by comma and for each new city we get suggestions as we type.


Hope that this demo will be useful to others and hope the explanations were clear enough. The AutoCompleteBox is a very useful control in lots of cases and with a bit of customization it can be quite powerful.

A very useful article that I read when I first started to use the control is AutoCompleteBox for WP7 in depth which provides plenty of valuable information about the various properties and events exposed by the control. If you need to learn more about the control, check it as it’s a very good resource.

The full project for this demo can be downloaded here – feel free to take it, run it and play with it.

Also, any comments or suggestions related to this demo are welcomed, so drop me a line in the comments if you have something to say.

Happy coding!