Getting Started with Underscore.js

This article was peer reviewed by Agbonghama Collins and Ryan Chenkie. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!

Underscore.js is a JavaScript library, written by Jeremy Ashkenas, that provides functional utilities for a variety of use cases that we, as developers, may come across when facing a web project.

It makes for code which is easier to read:

_.isEmpty({});
// true

It makes for code which is easier to write:

_.flatten([[0, 1], [2, 3], [4, 5]]);
// [0, 1, 2, 3, 4, 5]

It offers features for which there isn’t a 1:1 native method:

_.range(5);
// [0, 1, 2, 3, 4]

It can even be used as a template engine in its own right:

_.template('<p><%= text %></p>', {text: 'SitePoint Rocks!'});
// <p>SitePoint Rocks!</p>

Underscore is a lightweight library (just 5.7kb, minified and Gzipped) and is used by a variety of big name projects, such as:

• USA Today
• LinkedIn
• Khan Academy

Now let’s get more specific and start diving into its main capabilities.

The Good Parts

In this tutorial, I’m going to highlight three of Underscore’s most common methods:

• _.each()
• _.template()
• _.filter()

I’ll explain how they are used individually, then tie them together to build a demo application that you can find at the end of the tutorial. As ever, the code for this demo is available on Github.

If you wish to follow along with the examples, you’ll need to grab a copy of the library, for example from your favourite CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js"></script>

And if you find yourself in need of help along the way, or you’re just curious to find out more, don’t forget that Underscore’s documentation is extensive. It also has a large and active community, meaning help is easy to find.

_.each: Write Readable Loops

There is not a single project that does not have something similar to this snippet at some point in the code:

var artists = ['Pharrel Williams', 'Led Zeppelin', 'Rolling Stones'];

for(var i = 0; i < artists.length; i++) {
  console.log('artist: ' + artists[i]);
}

Underscore enables you to write equivalent code, using a syntax that is more readable:

var artists = ['Pharrel Williams', 'Led Zeppelin', 'Rolling Stones'];

_.each(artists, function(artist, index, artists) {
  console.log('artist: ' + artist);
});

Neat, eh? _.each() takes two parameters:

• The array (or object) to iterate over.
• A callback function.

For each element in our array _.each() will invoke the callback function (referred to in the documentation as iteratee). Inside the callback we get access to a further three parameters:

• The value of the array for the current iteration index (artist). For example, for the snippet above we’d get “Pharrel Williams” for the first iteration.
• The number of the current iteration (index), which in our case will vary from 0 to 2.
• The array that we are iterating through (artists).

As you can see the code is more readable and we can access the individual elements in the array without the need for artists[i], as we saw in the example that used a for loop.

See the Pen _.each by SitePoint (@SitePoint) on CodePen.

Next, we’ll see how the templating engine behaves.

_.template(): Intuitive and Straightforward

Since the rise of the Single Page Application, having a reliable frontend templating engine has become a fundamental need for our working stack.

Underscore provides a templating engine, which, for those familiar with languages such as PHP, or Ruby on Rails, will seem quite familiar.

Carrying on from our previous snippet, we’ll demonstrate how _.template() works. We’ll do this by adding a couple of lines to our code as shown below:

var artists = ['Led Zeppelin', 'ACDC', 'Rolling Stones'],
    artistTemplate = _.template('<li><%= artist %></li>'),
    content = '';

_.each(artists, function(artist, index, artists) {
  content += artistTemplate({
    artist: artist
  });
});

var container = document.createElement('ol');
container.innerHTML = content;
document.body.appendChild(container);

Here we are invoking the _.template() function with a string argument, which includes some data inside delimiters (<%= artist %>). When invoked in this way, _.template() returns a function which we can use again and again.

We can invoke our new function using artistTemplate(), passing it an object literal as an argument. This will return the string we originally passed to _.template(), substituting any object properties which correspond to the template’s free variables. In our case <%= artist %> will be substituted by the value in the artist attribute of the object.

Underscore’s templating engine, does not only allow for single values to be replaced, but also the execution of scripts inside the template itself. With a single modification, we can make our snippet even more powerful.

var artists = ['Led Zeppelin', 'ACDC', 'Rolling Stones'],
    artistTemplate = _.template(
      '<% _.each(artists, function(artist, index, artists) { %>' +
        '<li><%= artist %></li>' +
      '<% }); %>'
    ),
    content = artistTemplate({
      artists: artists
    });

var container = document.createElement('ol');
container.innerHTML = content;
document.body.appendChild(container);

We have incorporated our call to _.each() into the string that represents our template, which leads us to change the way the template is invoked. Since we are now iterating inside the _.template() function, we can pass the complete artists array to artistTemplate() (previously we were passing the individual artists). The output of this code will be the same as in the previous example.

When we want _.template() to evaluate JavaScript code, we just have to surround our code between <% %> instead of <%= %>.

Since invoking a template generated by _.template works just as invoking a function, we can take our snippet one step further and have one template called from inside another, by using the <% %> tags. This way, we can make reusable templates, since we can have a different wrapper template for our artists list and just invoke the template for each of the items it contains.

See the Pen _.template() by SitePoint (@SitePoint) on CodePen.

Finally, let’s take a look at the _.filter() function.

_.filter(): All You Need Is a Boolean Function

_.filter() receives an array and a callback function as arguments. It then invokes the function for each of the elements in the array and returns a new array containing those elements for which the function evaluated to something truthy.

Our callback function will also receive three arguments, as in the _.each() case: the element in the array corresponding to the current iteration index, the index of the iteration and the array itself.

To clarify this, let’s make a couple of modifications to our snippet.

var artists = ['Led Zeppelin', 'ACDC', 'Rolling Stones'],
    artistTemplate = _.template(
      '<% _.each(artists, function(artist, index, artists) { %>' +
        '<li><%= artist %></li>' +
      '<% }); %>'
    ),
    content = artistTemplate({
      artists: _.filter(artists, function(artist, index, artists) {
        return artist === 'ACDC';
      })
    });

var container = document.createElement('ol');
container.innerHTML = content;
document.body.appendChild(container);

As you may have guessed, in our template we’ll receive ['ACDC']as the array argument. Here’s a demo of what we’ve got so far.

See the Pen _.filter() by SitePoint (@SitePoint) on CodePen.

Enough said. Let’s get things working for something that makes a little more sense.

Our Demo Application

Don’t forget, the code for this demo is available on Github.

We’ll build a small application which consumes an API, displays the information obtained and allows the user to filter what is being shown. For this purpose we’ll be using:

• Underscore.js
• jQuery
• The Spotify Web API

More specifically, the application will fetch some artist information from Spotify and by using Underscore _.template, _.each and _.filter, we’ll display it on the page and allow the user to narrow the results by genre.

To do this, we’ll divide our code into three different modules:

• _isAwesome.Config: holds the information that we’ll use across the application.
• _isAwesome.Template: takes care of the template compilation.
• _isAwesome: this is the main module which is responsible for responding to user actions and updating the UI.

All of them follow the Module Pattern.

Config Module

The Config module contains the ids of the templates to be used, together with the URL of the API that we’ll query, plus the ids of the artists that we want to get from Spotify. This way, we can add more artists by just adding further elements to the array.

Template Module

This module is the one in charge of compiling the templates, by calling getTemplates() in the Config module.

Main Module

This module is responsible for sending the Ajax request to the URL we get from the Config module and rendering the content using the templates from the Template module.

Aside from that, this module also takes care of filtering the items based on the filter clicked by the user.

Both the filters and our templates are included as part of the HTML.

To implement the filtering, we will rely on HTML 5 data attributes and jQuery’s data interface. This is more a question of convenience, but should you wish to do this natively, browser support is very good.

This is the markup of the buttons we’ll use to do the filtering:

<button class="btn btn-default sized"
        data-filter-field="genres"
        data-filter-value="album rock"
        data-action="filter">Album Rock</button>

This is an example of an object we’ll be passing to our filter function:

{
  action: 'filter',
  field: 'genres',
  value: 'rock'
}

We’ll have the HTML for our templates as part of our index.html, inside a <script> tag, which we prevent from being executed by setting its type to something different than the usual text/javascript. Just for the sake of consistency we’ll set it to underscore/template.

We’ll have two templates. The first will contain the list of artists, whereas the second will contain the individual artists to be displayed. As we saw above, we’ll use what we call embedded templates. We’ll be invoking one template ('item-tpl') from within another one ('item-list').

Then, at the bottom of the file we’ll include our libraries and our three scripts. Also, just to make it more visually appealing, we’ll have some basic styles in the header.

And that’s it.

See the Pen Underscore Awesomeness by SitePoint (@SitePoint) on CodePen.

Conclusion

Underscore is a joy to work with and, as I have demonstrated, it allows you to write clean, readable and easy-to-maintain code.

There are a couple more things that we could have added to our application (e.g. having our filters dynamically generated by using _.pluck()), but I think we have enough as to get started.

How about you? Have you worked with Underscore? Would you be willing to give a try? Did you try an alternative (i.e. lodash) that provides similar capabilities? Let me know in the comments below.

Frequently Asked Questions (FAQs) about Underscore.js