Guide · Open source

How to use mustache.js: render templates in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

mustache.js is a zero-dependency JavaScript implementation of the Mustache template system. It fills placeholders such as {{name}} in a text template with values from an object, and it works in web browsers, Node.js and CouchDB views. This guide shows you how to install it, render a template, and use variables, sections and inverted sections so you can produce text or HTML from a template.

mustache.jsjanl/mustache.js · ★ 16.7k · MIT Install options & downloads

Quick start

1Install the package. Run npm install mustache --save in your project. Make sure Node.js is available first.
2Require or import Mustache. Load the library with require('mustache') in Node.js or through a supported module system in the browser.
3Write a template string. Use double mustaches for tags, such as {{title}}, and section tags like {{#items}} where you need repeated blocks.
4Prepare a view object. Create an object whose keys match the tag names, with values, nested objects, lists or functions.
5Call Mustache.render. Pass the template and the view to Mustache.render and use the returned string.
6Insert the output. Place the rendered string into the page, for example with innerHTML, remembering that variables are escaped by default.

What is mustache.js and where can you use it?

Mustache is a logic-less template syntax that can be used for HTML, config files, source code or anything else. mustache.js expands tags in a template using values from a hash or object.

You can use mustache.js anywhere you can use JavaScript, including web browsers, server-side environments such as Node.js, and CouchDB views. It supports the CommonJS, AMD and ECMAScript module APIs, and it can also be used as a command line tool.

Install mustache.js with npm

You can get Mustache via npm. Run the following command in your project folder.

Node.js is listed as the prerequisite for the npm install. The README excerpt does not specify a required Node.js version.

$ npm install mustache --save

Render your first template

The Mustache.render function takes two parameters: the template string and a view object that contains the data and code needed to render the template. Tags are wrapped in double mustaches, so {{title}} is a tag whose key is title.

const Mustache = require('mustache');

const view = {
  title: "Joe",
  calc: () => ( 2 + 4 )
};

const output = Mustache.render("{{title}} spends {{calc}}", view);

Use variables and control HTML escaping

A {{name}} tag renders the value of the name key in the current context. If there is no such key, nothing is rendered. Dot notation such as {{name.first}} reaches properties of nested objects.

All variables are HTML-escaped by default. Use the triple mustache {{{name}}} or the & character to output unescaped HTML. The README also explains that you can override Mustache.escape globally, for example to template non-HTML formats.

View:
{
  "name": "Chris",
  "company": "<b>GitHub</b>"
}

Template:
* {{name}}
* {{age}}
* {{company}}
* {{{company}}}
* {{&company}}

Output:
* Chris
*
* &lt;b&gt;GitHub&lt;/b&gt;
* <b>GitHub</b>
* <b>GitHub</b>

Repeat blocks with sections

A section begins with {{#person}} and ends with {{/person}}. If the key is missing, null, undefined, false, 0, NaN, an empty string or an empty list, the block is not rendered. If the key is a list, the block renders once for each item, and the context becomes that item.

Inside a loop over strings, a single dot refers to the current item. Inverted sections, which open with {{^section}}, render only when the value is empty or falsy, which is useful for a fallback message.

{{#stooges}}
<b>{{name}}</b>
{{/stooges}}

{{#repos}}<b>{{name}}</b>{{/repos}}
{{^repos}}No repos :({{/repos}}

Load templates from the page or from files

For a static website, you can include the template inside the HTML file in a script tag with a custom type, read its innerHTML, and pass it to Mustache.render. Alternatively, keep templates in separate files and load them with fetch, then render them when the response arrives.

Comments begin with a bang and are ignored, for example {{! ignore me }}.

Include the template in the HTML to avoid loading templates separately.
Load individual template files asynchronously with fetch.

function renderHello() {
  fetch('template.mustache')
    .then((response) => response.text())
    .then((template) => {
      const rendered = Mustache.render(template, { name: 'Luke' });
      document.getElementById('target').innerHTML = rendered;
    });
}

What people use it for

Filling a small dynamic part of a static website from an HTML template.
Rendering a list of items with a section that loops over an array.
Showing a fallback message with an inverted section when a list is empty.
Letting non-programmers edit text templates that contain only simple tags.
Rendering text templates in a Node.js script or a CouchDB view.

Frequently asked questions

How do I install mustache.js?

Install it from npm with npm install mustache --save. The README lists Node.js as the prerequisite and says you can get Mustache via npm.

Is mustache.js free to use?

mustache.js is released under the MIT licence, as shown in the project information for janl/mustache.js.

Does mustache.js need other dependencies?

mustache.js is described as a zero-dependency implementation of the Mustache template system.

Why does my HTML show up as escaped text?

Variables are HTML-escaped by default. Use triple mustaches like {{{name}}} or the & character, such as {{&name}}, to output unescaped HTML.

Can I use if statements or loops in mustache templates?

No. Mustache is logic-less and has no if statements, else clauses or for loops. Sections and inverted sections cover repetition and conditional-style rendering.

What are the alternatives to mustache.js?

The project lists Handlebars.js, Pug, EJS and Nunjucks as comparable projects. Pick one based on whether you need logic inside templates.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

mustache.js suits developers who want simple, zero-dependency text or HTML templating in a browser or Node.js project, and it works well when non-programmers need to edit templates. If your templates need complex logic, or you want a full web framework rather than string rendering, consider a comparable project such as Handlebars.js, Pug, EJS or Nunjucks.

Install options & downloads