Guide · Open source
How to use Handlebars.js: templates, data and helpers
Updated · written with AI from the project's own documentation and checked against our catalogue data
Handlebars.js is a JavaScript templating library. You write a template with placeholders like {{name}}, plus loops and conditions, then combine it with a data object to produce HTML or text. This guide walks through compiling and rendering a template, precompiling, custom helpers, and the differences from Mustache so you know what to expect before you build with it.
Handlebarshandlebars-lang/handlebars.js · ★ 18.7k · MIT Install options & downloads Quick start
- 1Install or load the library. Follow the installation guide at handlebarsjs.com for Node.js or a modern browser. The README lists those as the prerequisites.
- 2Write a template string. Use placeholders such as {{name}} and block expressions such as {{#kids}}...{{/kids}} inside a string.
- 3Compile the template. Call Handlebars.compile with your source string to get a template function.
- 4Render with data. Call the template function with a data object to produce the final HTML or text.
- 5Optionally precompile. Precompile templates to include them as JavaScript code and reduce startup work, following the precompilation guide.
- 6Add custom helpers. Write helpers for formatting values you reuse across templates; helpers take priority in name conflicts.
What Handlebars.js is and when to use it
Handlebars provides the power necessary to let you build semantic templates. Developers use it to generate page markup in browsers or on servers without writing string-building code by hand.
It is largely compatible with Mustache templates, so in most cases you can swap Mustache out for Handlebars and keep your current templates.
- JavaScript developers who need to generate HTML from data in a browser or Node.js app
- Teams migrating from Mustache who want a mostly compatible syntax
- Projects that want precompiled templates to reduce startup work
- Developers who need custom reusable helpers for formatting values
Install Handlebars.js and check prerequisites
The prerequisites are Node.js or a modern browser. The project's installation documentation is on handlebarsjs.com, and the README points there for installation instructions.
The README also lists a clone command for the repository: git clone https://github.com/handlebars-lang/handlebars.js. Cloning gives you the source code; for normal use, follow the installation guide on the official docs site.
git clone https://github.com/handlebars-lang/handlebars.jsWrite a template and compile it with Handlebars.compile
Write your template as a string using placeholders such as {{name}}. Pass the string to Handlebars.compile, which returns a function. Call that function with a context object, and it renders the template with your data.
Nested values can be reached with paths such as {{kids.length}}, and {{#kids}}...{{/kids}} repeats a block for each item in a list.
- Compile once with Handlebars.compile(source) and reuse the returned function
- Pass a data object as the context argument when you call the template
var source = '<p>Hello, my name is {{name}}. I am from {{hometown}}. I have ' + '{{kids.length}} kids:</p>' + '<ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>';
var template = Handlebars.compile(source);
var result = template({ name: 'Alan', hometown: 'Somewhere, TX', kids: [{ name: 'Jimmy', age: '12' }, { name: 'Sally', age: '4' }] });Precompile templates for faster startup
Handlebars allows templates to be precompiled and included as JavaScript code rather than as template source. The project says this allows for faster startup time. The full details are in the precompilation guide on handlebarsjs.com.
Create custom helpers for formatting values
Helpers are explicit pieces of code that can implement whatever behavior you need. They are useful for formatting values in a reusable way. In the case of name conflicts, helpers are given priority over other lookups.
Block expressions use the same syntax as Mustache sections but behave differently. Sections act like an implicit each or with depending on the input data, while helpers are explicit code.
Know the differences from Mustache
Handlebars adds nested paths, helpers, block expressions, literal values and delimited comments. It also changes a small detail of how partials work.
Some Mustache behaviors are not implemented. Recursive lookup is off by default and needs the compile-time compat flag, which has a performance cost. Mustache-style lambdas are not supported, and alternative delimiters are not supported. Handlebars also does not allow a space between {{ and a command character, so {{> partial }} is allowed but {{ > partial }} is not.
- Recursive lookup requires the compat flag and is slower; prefer explicit path references where performance matters
- Mustache lambdas are not supported
- Alternative delimiters are not supported
- Use Handlebars version 4 if you must support environments older than ECMAScript 2020
Check browser and Node.js support
Handlebars is designed to work in any ECMAScript 2020 environment, including Node.js, Chrome, Firefox, Safari and Edge. If you need to support older environments, the README says to use Handlebars version 4.
What people use it for
- Generating page markup in a browser from a JavaScript data object
- Rendering HTML or text on a Node.js server from data
- Migrating existing Mustache templates to a mostly compatible syntax
- Shipping precompiled templates to reduce startup work
- Writing reusable helpers that format values in templates
Frequently asked questions
How do I install Handlebars.js?
The README points to the installation documentation at handlebarsjs.com/guide/installation, which covers setup. The README also lists a git clone of the repository, but for normal use follow the official installation guide.
What do I need to run Handlebars.js?
The listed prerequisites are Node.js or a modern browser. The library is designed to work in any ECMAScript 2020 environment.
Is Handlebars.js free to use?
Handlebars.js is released under the MIT licence, as stated in the project's licence information.
Can I use my existing Mustache templates with Handlebars?
Often yes. The README says Handlebars is largely compatible with Mustache, and in most cases you can swap Mustache for Handlebars. Check the differences list, since Mustache lambdas and alternative delimiters are not supported.
Which version should I use for older browsers?
If you need to support environments older than ECMAScript 2020, the README says to use Handlebars version 4.
Where do I find known issues and common pitfalls?
The README links to FAQ.md in the repository for known issues and common pitfalls, and to release-notes.md for upgrade notes.
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
Handlebars.js suits JavaScript developers who need to generate HTML from data in a browser or Node.js app, especially teams moving from Mustache. Pick something else if you need Mustache lambdas or alternative delimiters, must support environments older than ECMAScript 2020 on the current version, or want a no-code site builder.
Install options & downloads