New to Telerik UI for WinForms? Download free 30-day trial


The RadAutoCompleteBox can automatically complete the input string by comparing the prefix being entered to the prefix of all strings in the maintained source. This is useful for RadAutoCompleteBox where URLs, addresses, file names or commands will be frequently entered.

There are four different modes:

  • Append: Appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters.

  • None: - disables the automatic completion feature.

  • Suggest: - Displays the auxiliary drop-down list associated with the edit control. This drop-down is populated with all matching completion strings.

  • SuggestAppend: - Applies both Suggest and Append options.

You can change the completion behavior by setting the AutoCompleteMode property. You can determine the items used for auto-completion by specifying a data source or adding the items manually.

Auto-completion data binding

RadAutoCompleteBox can be bound to the following data sources:

  • Array and ArrayList of simple types or custom objects.

  • Generic Lists of simple types or custom objects.

  • BindingList or other IBindingList implementations.

  • Database data using DataTable and DataSet from a wide range of providers (MS SQL, Oracle, Access, anything accessible through OleDb).

Three properties control data binding:

  • The AutoCompleteDataSource property specifies the source of the data to be bound.

  • The AutoCompleteDisplayMember property specifies the particular data to be displayed in the auto-completion drop down.

  • The AutoCompleteValueMember property specifies the particular data to be returned as the value of the tokenized block element.

To set the AutoCompleteDataSource property, select the AutoCompleteDataSource in the Properties window of Visual Studio, click the drop-down arrow to display all existing data sources on the form. Click the Add Project Data Source link and follow the instructions in the Data Source Configuration Wizard to add a data source to your project. You can use databases, web services, or objects as data sources.

Figure 1: The AutoCompleteDataSource property in Visual Studio.

WinForms RadAutoCompleteBox The AutoCompleteDataSource property in Visual Studio

AutoCompleteDisplayMember: To set the AutoCompleteDisplayMember property, first set the data source property. Then, select a value for the AutoCompleteDisplayMember property from the drop-down list in the Properties window.

AutoCompleteValueMember: To set the AutoCompleteValueMember property, first set the AutoCompleteDataSource property. Then, select a value for the AutoCompleteValueMember property from the drop-down list in the Properties window.

Auto-completion in unbound mode

To use auto-completion without specifying a data source, you need to populate the items which will be used for completing the input string in RadAutoCompleteBox in the Items collection of the control:

private void AddAutoCompleteItems()
    RadListDataItemCollection items = this.radAutoCompleteBox1.AutoCompleteItems;
    items.Add(new RadListDataItem("Joe Smith", ""));
    items.Add(new RadListDataItem("Adam Petersen", ""));
    items.Add(new RadListDataItem("Jack Russel", "jack@russel.nocom"));
    items.Add(new RadListDataItem("Daniel Finger", ""));
    items.Add(new RadListDataItem("Richard Vail", ""));
    items.Add(new RadListDataItem("Sebastian Jonnson", ""));
    items.Add(new RadListDataItem("Lee Cooper", ""));
    items.Add(new RadListDataItem("Kelvin Clain", ""));
    items.Add(new RadListDataItem("Maria Jenson", ""));
    items.Add(new RadListDataItem("Chelsea Maarten", ""));
    items.Add(new RadListDataItem("Jenson Chew", ""));
    items.Add(new RadListDataItem("Martin Williams", ""));
    items.Add(new RadListDataItem("Telerik", ""));
    items.Add(new RadListDataItem("James Stone", ""));
    items.Add(new RadListDataItem("Samuel Jackson", ""));

Private Sub AddAutoCompleteItems()
    Dim items As RadListDataItemCollection = Me.RadAutoCompleteBox1.AutoCompleteItems
    items.Add(New RadListDataItem("Joe Smith", ""))
    items.Add(New RadListDataItem("Adam Petersen", ""))
    items.Add(New RadListDataItem("Jack Russel", "jack@russel.nocom"))
    items.Add(New RadListDataItem("Daniel Finger", ""))
    items.Add(New RadListDataItem("Richard Vail", ""))
    items.Add(New RadListDataItem("Sebastian Jonnson", ""))
    items.Add(New RadListDataItem("Lee Cooper", ""))
    items.Add(New RadListDataItem("Kelvin Clain", ""))
    items.Add(New RadListDataItem("Maria Jenson", ""))
    items.Add(New RadListDataItem("Chelsea Maarten", ""))
    items.Add(New RadListDataItem("Jenson Chew", ""))
    items.Add(New RadListDataItem("Martin Williams", ""))
    items.Add(New RadListDataItem("Telerik", ""))
    items.Add(New RadListDataItem("James Stone", ""))
    items.Add(New RadListDataItem("Samuel Jackson", ""))
End Sub

Figure 2: RadAutoCompleteBox with some items added directly.

WinForms RadAutoCompleteBox With Some Items Added Directly

Allow Duplicates

As of R1 2020 SP1 RadAutoCompleteBox offers the AllowDuplicates property. It controls whether already selected items can be suggested.

AllowDuplicates=true AllowDuplicates=false
WinForms RadAutoCompleteBox AllowDuplicates True WinForms RadAutoCompleteBox AllowDuplicates False

Note that you can still add duplicated tokens in the editor if you type them manually. In order to avoid that you can subscribe to TokenValidating event and if the existing text in RadAutoCompleteBox contains the new text, set the IsValidToken property to false. The TokenValidating event will be called for each token that is going to be added to the control text area.

              private void RadAutoCompleteBox1_TokenValidating(object sender, TokenValidatingEventArgs e)
            if (this.radAutoCompleteBox1.Text.Contains(e.Text))
                e.IsValidToken = false;

          Private Sub RadAutoCompleteBox1_TokenValidating(ByVal sender As Object, ByVal e As TokenValidatingEventArgs)
        If Me.radAutoCompleteBox1.Text.Contains(e.Text) Then
            e.IsValidToken = False
        End If
    End Sub   

See Also

In this article