Sunday, 6 November 2016

Twitter 3 Bootstrap Autocomplete control for MVC 5 - Typeahead.js

This article will present a reusable user control for MVC applications using Twitter Bootstrap autocomplete feature. This feature is known as the Twitter Bootstrap typeahead. There is a lot of articles covering this topic on the Internet, my version will present a simple reusable control using MVC html helper that generates input fields of type text and hidden, i.e. a textbox and a hidden field to save the value. The MVC model binder will therefore be able to save the selected value in the list showing up in the autocomplete-enabled textbox into the target property specified. Of course, your needs for autocomplete feature will vary. The control described in this article will suit many developer's needs as they call up a controller action to get the desired data and then filter the drop down and also use the Bloodhound engine of Twitter to mark up the matches quite nicely. The end result is a very useful and nicely styled autocomplete textbox! It also supports keyboard navigation with arrow keys and Enter! Read on! Let's first look at the MVC Html helper itself first:

using System;
using System.Linq.Expressions;
using System.Web.Mvc;

namespace TwitterBootstrapAutoCompleteControl.HtmlHelpers

    public static class CustomMvcHelpers

        public static MvcHtmlString AutoCompleteFor<TModel, TResult>(this HtmlHelper<TModel> htmlHelper,
            Expression<Func<TModel, TResult>> propertyToSet, string fetchUrl)
            var metaData = ModelMetadata.FromLambdaExpression(propertyToSet, htmlHelper.ViewData);
            string propertyName = metaData.PropertyName;
            string jsComponent = string.Format(
              <input type ='hidden' id='{0}' />   
              <input type='text' id='{1}' class='typeahead form-control' placeholder='Search some values' />             
              <script type='text/javascript'> 
              <!-- AutoCompleteFor -->
              $(function() {{

                var suggestionEngine = new Bloodhound({{
                limit: 300,
                datumTokenizer: function(datum) {{
                queryTokenizer: Bloodhound.tokenizers.whitespace,
                    url: '{2}',
                    filter: function(response) {{
                    var matches = [];
                    $.map(response, function(item) {{
                            var query = $('#{1}').val().toLowerCase();
                            var itemKey = item.Text.toLowerCase();                          
                            if (itemKey.indexOf(query) >= 0)

                        return matches;


                hint: true,
                highlight: true,
                minLength: 1,           
        }}   , {{
                limit: 30,
                displayKey: 'Text',
                source: suggestionEngine.ttAdapter(),
                filter: function(data) {{
                    return data;
                    suggestion: function(data) {{
                        return '<p>' + data.Text + '</p>';
                empty: [
                'No results matching',

            $('#{1}').bind('typeahead:select', function(ev, suggestion) {{
             //console.log('Selection: ' + suggestion.Text);




     ", propertyName, propertyName + "TextBox", fetchUrl);

            return MvcHtmlString.Create(jsComponent);



The MVC html helper will generate the HTML and the javascript that is required to generate a textbox and a hidden field with the autocomplete feature. Your MVC solution needs to include both jQuery and Twitter Bootstrap, plus the Twitter typeahead.js Nuget packages. In addition, you need to include the Bloodhound javascript file. Let's look at a controller action return Json data to our Html helper, which will use javascript to call that method:

        public ActionResult SomeData()
            var countries = new List
            new IdTextItem {Id = "US", Text = "United States"},
            new IdTextItem {Id = "CA", Text = "Canada"},
            new IdTextItem {Id = "AF", Text = "Afghanistan"},
            new IdTextItem {Id = "AL", Text = "Albania"},
            new IdTextItem {Id = "DZ", Text = "Algeria"},
            new IdTextItem {Id = "DS", Text = "American Samoa"},
            new IdTextItem {Id = "AD", Text = "Andorra"},
            new IdTextItem {Id = "AO", Text = "Angola"},
            new IdTextItem {Id = "AI", Text = "Anguilla"},
            new IdTextItem {Id = "AQ", Text = "Antarctica"},
            new IdTextItem {Id = "AG", Text = "Antigua and/or Barbuda"}

            return Json(countries, JsonRequestBehavior.AllowGet);


The Json method returns a JsonResult that is called once by this html helper. We filter the data on the client as can be seen in the Html Helper code. Let's look at the script bundle added in BundleConfig

   bundles.Add(new ScriptBundle("~/bundles/typeahead").Include(

This Html helper will fetch data on load, while it is the text that the user is typing that filters the autocomplete list. If you need to pass in a text and use that in your fetchUrl, the html helper's filtering most likely can be adjusted, also look into the prefetch property of the typeahead. We also move up jQuery bundle to the top as the default MVC template has this bundle in the footer and not in the header, as will be required by the typeahead feature. Place in the section of _Layout.cshtml: @Scripts.Render("~/bundles/jquery") And in the bottom of the element of that same file: @Scripts.Render("~/bundles/typeahead") The html helper expects that your class contains the properties Id and Text. You can of course use an anonymous type to avoid creating a new type in your C#-code. The type could be a string or an integer for the Id.

 public class IdTextItem

        public string Id { get; set; }

        public string Text { get; set; }


We also do some adjustments to the style, since the default setting of the typeahead is borishingly looking. Add the following css styling to your view - or better - in a standalone css to be included in _Layout.cshtml. Save the following content into typeahead.css file which you place in the Content folder:

.tt-query {
  -webkit-box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);
     -moz-box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);
          box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);

.tt-hint {
  color: #999

.tt-menu {    /* used to be tt-dropdown-menu in older versions */
  width: 422px;
  margin-top: 4px;
  cursor: pointer;
  padding: 4px 0;
  background-color: #fff;
  border: 1px solid #ccc;
  border: 1px solid rgba(0, 0, 0, 0.2);
  -webkit-border-radius: 4px;
     -moz-border-radius: 4px;
          border-radius: 4px;
  -webkit-box-shadow: 0 5px 10px rgba(0,0,0,.2);
     -moz-box-shadow: 0 5px 10px rgba(0,0,0,.2);
          box-shadow: 0 5px 10px rgba(0,0,0,.2);

.tt-suggestion {
  padding: 3px 20px;
  line-height: 24px;
},.tt-suggestion:hover {
  color: #fff;
  background-color: #0097cf;


.tt-suggestion p {
  margin: 0;

Then adjust the StyleBundle in BundleConfig to include this css file:
      bundles.Add(new StyleBundle("~/Content/css").Include(
Finally, here is an example of how to use this Html Helper:

<div class="row">
    <div class="col-md-4">    
        <h2>Autocomplete control html helper:</h2>   
        @Html.AutoCompleteFor(m => m.SomeProperty, Url.Action("SomeData", "Home"))

The call to the html helper provides as the first argument the property of the Model of the MVC View and the second argument is an url to the action to fetch the data. This HTML helper should match a lot of developer's needs, but can of course be adjusted. The benefit of using a MVC Html helper is that you get reusability. You avoid having to fiddle with Javascript for each field you want to add to your MVC view where you want some autocomplete feature. Maybe you want to adjust the HTML helper to fit your needs. I have provided a link to a zip file of this Html Helper in a Visual Studio 2015 below, let me know if there are some tips or improvement you have in case you evaluate and test out this Html helper and find improvements. Note that the chosen value in the autocomplete list is set to a hidden field. The textbox will be named "propertyname"TextBox and the hidden field will be named "propertyname"

Download the source code for the autocomplete control (VS 2015 solution):

Download zip file [.zip | 31,7 MB] Reading material:


  1. This comment has been removed by the author.

  2. After changing "var countries = new List"
    to "var countries = new List< IdTextItem >"
    and adding a dropdown to the display of countries, this works well.
    Good basic example.