Creating a Typeahead Widget with AngularJS

Share this article

If you are starting an AngularJS project you might want to have all the components written in Angular. Although it’s certainly possible to reuse the existing jQuery plugins, throwing a bunch of jQuery inside a directive is not always the correct way to do things. My advice would be to first check if the same thing can be implemented with pure Angular in a simpler/better way. This keeps your application code clean and maintainable. This tutorial, targeted towards beginners, walks the readers through the creation of a simple TypeAhead widget with AngularJS.

Key Takeaways

  • The tutorial guides readers through creating a TypeAhead widget with AngularJS, which provides suggestions as a user types into a text box. The widget is designed to be highly configurable and easily integrated into existing systems.
  • The process involves building a factory that interacts with a RESTful API and returns JSON data for auto-complete suggestions, creating a directive to encapsulate the typeahead input field, and creating a template for the directive. The directive is kept configurable for end users to adjust options such as the JSON object properties to show as part of the suggestions and the model in the controller’s scope that will hold the selected item.
  • The tutorial also explains how to update the link function of the directive and configure the directive for use. The final product is an AngularJS TypeAhead widget with configuration options, which can be customized further using CSS. The complete source code is available for download on GitHub.

Overview

In this tutorial we are going to build a simple TypeAhead widget which creates suggestions as soon as someone begins typing into a text box. We will architect the app in such a way that the final product will be very configurable and can be plugged into an existing system easily. The basic steps involved in the creation process are:
  • Create a factory that interacts with a RESTful API, and returns JSON that will be used for auto complete suggestions.
  • Create a directive that will use the JSON data and encapsulate the typeahead input field.
  • Keep the directive configurable so that end users can configure the following options.

Configuration Options

  1. The exact JSON object properties to show as part of the suggestions.
  2. The model in the controller’s scope that will hold the selected item.
  3. A function in the controller’s scope that executes when an item is selected.
  4. A placeholder text (prompt) for the typeahead input field.

Step 1: Building a Factory for Getting Data

As the first step, let’s create a factory that uses Angular’s $http service to interact with RESTful APIs. Have a look at the following snippet:
var typeAhead = angular.module('app', []);

typeAhead.factory('dataFactory', function($http) {
  return {
    get: function(url) {
      return $http.get(url).then(function(resp) {
        return resp.data; // success callback returns this
      });
    }
  };
});
The previous code creates a factory called dataFactory that retrieves JSON data from an API. We won’t go into the details of the factory, but we need to briefly understand how the $http service works. You pass a URL to the get() function, which returns a promise. Another call to then() on this promise also returns another promise (we return this promise from the factory’s get() function). This promise is resolved with the return value of the success callback passed to then(). So, inside our controller, we don’t directly interact with $http. Instead, we ask for an instance of factory in the controller and call its get() function with a URL. So, our controller code that interacts with the factory looks like this:
typeAhead.controller('TypeAheadController', function($scope, dataFactory) { // DI in action
  dataFactory.get('states.json').then(function(data) {
    $scope.items = data;
  });
  $scope.name = ''; // This will hold the selected item
  $scope.onItemSelected = function() { // this gets executed when an item is selected
    console.log('selected=' + $scope.name);
  };
});
The previous code uses an API endpoint called states.json that returns a JSON list of US States. When the data is available, we store the list in the scope model items. We also use the model name to hold the selected item. Finally, the function onItemSelected() gets executed when the user selects a particular state.

Step 2: Creating the Directive

Let’s start with the typeahead directive, shown below.
typeAhead.directive('typeahead', function($timeout) {
  return {
    restrict: 'AEC',
    scope: {
      items: '=',
      prompt: '@',
      title: '@',
      subtitle: '@',
      model: '=',
      onSelect: '&'
    },
    link: function(scope, elem, attrs) {
    },
    templateUrl: 'templates/templateurl.html'
  };
});
In the directive we are creating an isolated scope that defines several properties:
  • items: Used to pass the JSON list to the isolated scope.
  • prompt: One way binding for passing placeholder text for the typeahead input field.
  • title and subtitle: Each entry of the auto complete field has a title and subtitle. Most of the typeAhead widgets work this way. They usually (if not always) have two fields for each entry in the drop down suggestions. If a JSON object has additional properties, this acts as a way of passing the two properties that will be displayed in each suggestion in the dropdown. In our case the title corresponds to the name of the state, while subtitle represents its abbreviation.
  • model: Two way binding to store the selection.
  • onSelect: Method binding, used to execute the function in the controller scope once the selection is over.
Note: An example JSON response is shown below:
{
  "name": "Alabama",
  "abbreviation": "AL"
}

Step 3: Create the Template

Now, let’s create a template that will be used by the directive.
<input type="text" ng-model="model" placeholder="{{prompt}}" ng-keydown="selected=false" />
<br/>

<div class="items" ng-hide="!model.length || selected">
  <div class="item" ng-repeat="item in items | filter:model  track by $index" ng-click="handleSelection(item[title])" style="cursor:pointer" ng-class="{active:isCurrent($index)}" ng-mouseenter="setCurrent($index)">
    <p class="title">{{item[title]}}</p>
    <p class="subtitle">{{item[subtitle]}}</p>
  </div>
</div>
First, we render an input text field where the user will type. The scope property prompt is assigned to the placeholder attribute. Next, we loop through the list of states and display the name and abbreviation properties. These property names are configured via the title and subtitle scope properties. The directives ng-mouseenter and ng-class are used to highlight the entry when a user hovers with the mouse. Next, we use filter:model, which filters the list by the text entered into the input field. Finally, we used the ng-hide directive to hide the list when either the input text field is empty or the user has selected an item. The selected property is set to true inside the handleSelection() function, and set to false false (to show the suggestions list) when someone starts typing into the input field.

Step 4: Update the link Function

Next, let’s update the link function of our directive as shown below.
link: function(scope, elem, attrs) {
  scope.handleSelection = function(selectedItem) {
    scope.model = selectedItem;
    scope.current = 0;
    scope.selected = true;
    $timeout(function() {
      scope.onSelect();
    }, 200);
  };
  scope.current = 0;
  scope.selected = true; // hides the list initially
  scope.isCurrent = function(index) {
    return scope.current == index;
  };
  scope.setCurrent = function(index) {
    scope.current = index;
  };
}
The function handleSelection() updates the scope property, model, with the selected state name. Then, we reset the current and selected properties. Next, we call the function onSelect(). A delay is added because the assignment scope.model=selecteditem does not update the bound controller scope property immediately. It is desirable to execute the controller scope callback function after the model has been updated with the selected item. That’s the reason we have used a $timeout service. Furthermore, the functions isCurrent() and setCurrent() are used together in the template to highlight entries in the auto complete suggestion. The following CSS is also used to complete the highlight process.
.active {
  background-color: #C44741;
  color: #f2f2f2;
}

Step 5: Configure and Use the Directive

Finally, let’s invoke the directive in the HTML, as shown below.
<div class="container" ng-controller="TypeAheadController">
  <h1>TypeAhead Using AngularJS</h1>
  <typeahead items="items" prompt="Start typing a US state" title="name" subtitle="abbreviation" model="name" on-select="onItemSelected()" />
</div>

Conclusion

This tutorial has shown you how to create an AngularJS TypeAhead widget with configuration options. The complete source code is available for download on GitHub. Feel free to comment if something is unclear or you want to improve anything. Also, don’t forget to check out the live demo.

Frequently Asked Questions on Creating a Typeahead Widget with AngularJS

How can I customize the appearance of the typeahead dropdown?

Customizing the appearance of the typeahead dropdown can be achieved by using CSS. You can target the dropdown menu by using the class .dropdown-menu. For instance, if you want to change the background color and font color, you can use the following CSS code:

.dropdown-menu {
background-color: #f8f9fa;
color: #343a40;
}
Remember to include this CSS in your main CSS file or within the <style> tags in your HTML file.

How can I limit the number of suggestions in the typeahead dropdown?

Limiting the number of suggestions in the typeahead dropdown can be done by using the typeahead-min-length attribute. This attribute specifies the minimum number of characters that must be entered before typeahead starts to kick in. For example, if you want to start showing suggestions after the user has typed 3 characters, you can use the following code:

<input typeahead-min-length="3" ... />

How can I use an object selection functionality with typeahead?

To use an object selection functionality with typeahead, you can use the typeahead-on-select attribute. This attribute allows you to specify a function to be called when a match is selected. The function will be passed the selected item. For example:

<input typeahead-on-select="onSelect($item, $model, $label)" ... />
In your controller, you can define the onSelect function like this:

$scope.onSelect = function (item, model, label) {
// Do something with the selected item
};

How can I use typeahead with Bootstrap in AngularJS?

To use typeahead with Bootstrap in AngularJS, you need to include the ui.bootstrap module in your AngularJS application. This module provides a set of AngularJS directives based on Bootstrap’s markup and CSS. The typeahead directive can be used as follows:

<input typeahead="state for state in states | filter:$viewValue | limitTo:8" ... />
In this example, states is an array of states, $viewValue is the value entered by the user, and limitTo:8 limits the number of suggestions to 8.

How can I use typeahead with remote data in AngularJS?

To use typeahead with remote data in AngularJS, you can use the $http service to fetch data from a remote server. The typeahead attribute can be used to bind the input field to the fetched data. For example:

$scope.getStates = function(val) {
return $http.get('/api/states', {
params: {
name: val
}
}).then(function(response){
return response.data.map(function(item){
return item.name;
});
});
};
In your HTML, you can use the getStates function like this:

<input typeahead="state for state in getStates($viewValue)" ... />
In this example, getStates is a function that fetches states from a remote server based on the value entered by the user.

Sandeep PandaSandeep Panda
View Author

Sandeep is the Co-Founder of Hashnode. He loves startups and web technologies.

Angular Tutorialswidget
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week