Introduction to JavaScript templating using mustache.js

Published by | Thursday, December 27th, 2012

Recently I built a small website for an event in my area. This type of project required me to manage small amounts of data—information about speakers, bios, titles, and a description of the talks. I wanted to have a speakers page, but I also wanted a rotating promo built as a component I could use on the homepage, and on other pages to highlight the event’s speakers. That meant two different views for the same data.

This was the kind of problem I used to throw a quick SQL database at, but it really wasn’t worth the pain for this project as the amount of data was so minimal.  However, I didn’t want to resort to HTML because I knew the information would change often and be a pain to update. To solve the problem, I used a library called mustache.js. It’s pretty easy to use, and solves the problem with just a few lines of code.

Why mustache.js?

Mustache is a library that allows you to read in JSON formatted data and display it using templates you design with JavaScript. There are lots of similar libraries, such as underscore.js, handlebars.js, and dust.js. So why did I choose mustache?

I picked mustache because I wanted something simple. Some of the other libraries provide more functionality, but I didn’t need complexity. I needed to spend time building the site, not learning something new. And that’s the great thing about mustache.js—if you know JSON and a bit of JavaScript, it’s a cinch to implement. Although, you do need to know how to use the JSON format, so if you’re not familiar with JSON, make sure you take a look at this article on getting started with JSON for beginners. If you’re a member, you’ll want to watch my complete course JavaScript and JSON, which goes into even more detail.

Installing or using CDNs

As usual, you have two options for working with libraries. You can install them manually or use CDNs (content delivery networks). Mustache has implementations available for different languages. If you want to download a copy, go to this GitHub page to download mustache.js. Because we’re going to be loading JSON files from an external source, you’ll also need to install jQuery, to download a copy of jQuery you can go to their website.

If you’re just experimenting with the libraries, another option is to load the files from a CDN, a site that specializes in hosting popular libraries like In order to keep things simple for this article, I’m going to load things from that CDN.

Our data

Here’s what the structure of my data looked like (abbreviated). It’s just a simple object with an array containing the usual information people would need to find out about the event speakers.

Creating a page

Our page is going to be super simple. I’ll create a basic HTML document, and then create a <ul> tag with an id of talktitles. The list will be empty and will get filled up with data from our JSON file. I’ll also link, in order, to the jQuery and mustache.js libraries from the CDN.

Here’s what that code looks like:

Next, we’ll need to create the template. That’s pretty easy. You create a mustache.js template inside <script> tags. Normally, your page would interpret this as JavaScript and throw an error, but if we give the script a type of text/template, the browser’s JavaScript parser will ignore it. Our template will also need an ID because it’s how we’ll refer to it when we use JavaScript to target it.

Crafting our template

Here’s the code for our template. It should go after our call to the jQuery library.

This should be pretty to read. We want to print the titles for each of our speakers. Our template is simply HTML with double curly braces where we want the library to generate code for us. So, to output the title, we simply use {{title}} to output that field from our JSON file. In order to loop through each of the speakers, we use the {{#speakers}} because it’s the name of the array containing all of the speakers.

The reason a lot of these libraries have names related to facial hair is because of the all of the curly braces they use. This technique of putting data from a data file into a template is known as data binding.

Calling the data

To have our data load from the template, we use jQuery’s getJSON method. I can read any JSON file. We can pass the data into a function. We’re using an anonymous function here (a function with no name).

Inside this we can then create a variable called template and then use the jQuery html() method to read the contents of our template into a variable. Then, we use that template and the data with a call to the Mustache.to_html method from mustache.js that will return the HTML with the JSON data merged with our template.

Finally, we use jQuery to place that HTML inside our unordered list with the id of talktitles. Here’s that code:

Putting it all together

Here’s a full listing of the code:

You might have a problem when trying to read the JSON document if you don’t put this code on a server. For security reasons certain browsers (Google Chrome) don’t allow you to load external files on local folders. You can try using Safari, or just load the file on a live server.

The BarCamp Deland website - completed.

My Barcamp Deland project

For the final project, I used a more complicated template to drive the display of different elements on my page. The Featured Speakers rotating promo on the homepage as well as the data in the Speakers page. I also used this on a mobile app for the event, so changing a single text file updated the information in two or three places. You can see an example of the finished Barcamp Deland website for a more complex example of the code.

Share this:Share on Facebook3Tweet about this on Twitter9Share on Google+0Pin on Pinterest0Share on LinkedIn6 - start learning today

Tags: , , ,

8 Responses to “Introduction to JavaScript templating using mustache.js”

  1. Sergi says:

    You walk us through this so concisely, Ray. I’ve been hearing about mustache.js, underscore.js, etc for a year or two now but never trusted a tutorial to make it clear and concise enough.

    It’s great of you to offer up the JSON formatted data too. I attended/presented at BarCamp, LA once.

    it would be great if you did Lynda course that focused on API’s and JSON data and templating, maybe even going into differences between server side and client side templating. No front end developer position comes without questions regarding our experiences using API’s.

    i have a technical question related to this:
    at the following url, you’ll find some JSON. We don’t have the name of the array as you did (#speakers), so how can we still hook into this data as you did in your example?



  2. Sergi says:

    Hi, Ray,

    I had been testing the sample locally, using Coda and it was working fine. However, I’ve come to realize that it doesn’t work uploaded to a server; or in any of my local browsers (Safari, FF, Chrome). The json won’t parse. This includes the gist on GitHub. For some reason Coda is able to parse it in its local preview window.

    What do you suspect is the problem?


    • Hey Sergi,

      When you upload to a server, you have to make sure that the JSON and the HTML file are on the same server. This is called a same domain policy. It’s what’s probably happening. You might be placing the JSON file on the server, but trying to access the HTML file locally.

  3. ash khan says:

    i really appreciate the way you explained this library awesome Ray……
    keep working cos its helping alot.
    thank you so much.

  4. Richard says:


    I followed your great JSON course and just curious about one issue I have. I have UL 2 lists using the example above and ie a products list & grid view. The list view displays great but when I click the grid view tab nothing shows on this tab. My question is does mustache not render into inactive div’s or do i need to alter the script to take account of a click event?

  5. Bhargavi says:

    thanQ for this tutorial

Leave a Reply