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
- The exact JSON object properties to show as part of the suggestions.
- The model in the controller’s scope that will hold the selected item.
- A function in the controller’s scope that executes when an item is selected.
- 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 thetypeahead
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 thetypeahead
input field.title
andsubtitle
: Each entry of the auto complete field has atitle
andsubtitle
. Most of thetypeAhead
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 thetitle
corresponds to the name of the state, whilesubtitle
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.
{
"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 is the Co-Founder of Hashnode. He loves startups and web technologies.