Light-weight DOM-based template engine, inspired by AngularJS

Downloads in past


1.0.07 years ago8 years agoMinified + gzip package size for ng-template in KB


ngTemplate 1.0
Build Status
ngTemplate is a light-weight DOM-based template engine, inspired by AngularJS.
mustache.js, Handlebars or _.template are all nice and shiny, until it comes to a form. With every rending these template engines replace the bound DOM subtree and the state of inputs gets lost.
ngTemplate treats the DOM carefully. It modifies the exact target nodes gracefully according to the directives and actual state.


  • Progressive enhancement friendly: Server-side generated HTML can be fully ready for presentation. During ngTemplate synchronization it will be updated according to element directives and a provided state
  • HTML compliant: data-* - directives instead of foreign concepts such as {{foo}}, [hidden], *ngFor, [(ngModel)]
  • Concern separation: Presentation state logic decoupled from the view
  • Performance: ngTemplate modifies DOM nodes by state diff; it touches the DOM only when it's necessary
  • Easy to catch up: Familiar for Angular folks directives such as data-ng-if, data-ng-switch, data-ng-for and a few extra intuitive e.g. data-ng-text, data-ng-class
  • Really small library: minimized gziped size is 4K
  • Definitely Typed: IDE checks on the fly if you violate any of declared interfaces (if not the compiler does)

How does it work?

Templates are written with HTML that contains ngTemplate-specific data attributes (data-ng-*):
<form id="heroForm" novalidate>
  <div class="form-group">
    <label for="name">Name</label>
    <input id="name" type="text" class="form-control" required >
    <div class="alert alert-danger" data-ng-if="!name.valid">
      Name is required
  <div class="form-group">
    <label for="power">Hero Power</label>
    <select id="power" class="form-control"  required>
      <option data-ng-for="let p of powers" data-ng-text="p" >Nothing here</option>
    <div class="alert alert-danger" data-ng-if="!power.valid">
      Power is required
   <button type="submit" class="btn btn-default" data-ng-prop="'disabled', !form.valid">Submit</button>

ngTemplate synchronizes the template with the passed state. Let's say we have the template HTML within a DOM element, so we initialize the template like let template = new NgTemplate( el );. Alternatively we can populate the bounding element with the template from the passed string: let template = new NgTemplate( el, '<i data-ng-if="foo">Hello!</i>' );

As soon as we have template object we can sync it to a specified scope. E.g. template.sync({ foo: true }); makes variable foo available for template expressions, template.sync({ foo: { bar: true }}); gets accessable as
import { NgTemplate } from "ng-template";

let el = document.querySelector( "#heroForm" ),
    elName = document.querySelector( "#name" ),
    elPower = document.querySelector( "#power" );

// Bind the template
let template = new NgTemplate( el );

// Set the scope (view state)
let scope = {
  powers: [ "-", "Really Smart", "Super Flexible",
            "Super Hot", "Weather Changer" ],
  power: {
    valid: true
  name: {
    valid: true
  form: {
    valid: false
// Sync to the scope
template.sync( scope );

Live Demo

ngTemplate Demo: Hero


You can get ngTemplate via npm.
npm i --save ng-template

Accessing module


import { NgTemplate } from "ng-template";
const template = new NgTemplate( node );


var NgTemplate = require( "ng-template" ).NgTemplate,
    template = new NgTemplate( node );
In order to adapt your source for browser, you can either browserfy or load your modules with SystemJS
  paths: {
     "*": "node_modules/*"
  packageConfigPaths: [ "./node_modules/*/package.json" ]


<script src=""./node_modules/ng-template/dist/ngtemplate.glob.min.js"></script>
var template = new NgTemplate( node );


import { NgTemplate } from "ng-template";
let template = new NgTemplate( el, tpl ); // compile template
template.sync( scope ); // render on the first run and after synchronize it with the scope
// optional
console.log( ); // find the synchronization details

  • el - a DOM element we bind to
  • tpl - OPTIONAL: template code that will be injected into el
  • scope - an object literal (template scope) whose members form the scope for template expressions

Also can be instantiated via the factory:
NgTemplate.factory( el, tpl )
  .sync( scope );


You can define though the constructor options the callbacks willMount and didMount. The first one gets invoked straight before the ngTemplate populates bounding element's inner HTML from the template string. ngTemplate calls the second callback after that:
import { NgTemplate } from "ng-template";
let template = new NgTemplate( el, tpl, {
 willMount: function(){
    console.log( "Template is up to initial rendering" );
  didMount: function(){
    console.log( "Template just finished initial rendering" );

Template expressions

Template expressions are being evaluated in the given scope. So we can reference scope variables within template e.g. data-ng-if="foo" refers to foo variable of the scope and therefore:
template.sync({ foo: true }); // show element
template.sync({ foo: false }); // hide element

We access scope objects the same way we do it in JavaScript e.g. data-ng-if="" refers to and can be toggled like this:
template.sync({ foo: { bar: true } }); // show element

Expressions may have mixed scope variables and primitives:
data-ng-if="foo && bar.baz || false"
data-ng-if="foo + 10  > 20"

We can pass rendering helpers (e.g. transformers) with the scope. For example we pass decorator to the directive data-ng-if="decorator(foo)" this way:
  foo: "foo",
  decorator: function( val ){
    return "decorated " + val;

Expressions are evaluated in the context of the target element, so we can access the element with this:
data-ng-if="foo && this.checked"

:exclamation: NOTE: In order to gain better performance keep to primitive expressions especially in cyclic directives e.g. data-ng-text="", data-ng-text="!", data-ng-text="'string here'", data-ng-if=" > baz.quiz", data-ng-text="foo + 10, data-ng-if="true", data-ng-prop="'disabled', true || false", data-ng-data="foo || bar, baz". Such expressions are being evaluated without use of eval() and therefore the process takes much less time and resources. You can check how the parser treats your expressions by studying content of array

ngTemplate Report

You can get template synchronization details like that:
let tpl = new NgTemplate(
  document.createElement( "div" ),
  "<span data-ng-text=\"\"></span>"

console.log( ); // [ "'' is undefined" ]



We use ngText to modify element's textNode


<el data-ng-text="expression => text:string|number" />


(new NgTemplate( document.body , `<i data-ng-text="foo"></i>` ))
  .sync({ foo: "Foo" });

console.log( document.body.innerHTML ); // <i>Foo</i>

HTML gets automatically escaped:
(new NgTemplate( document.body , `<i data-ng-text="foo"></i>` ))
  .sync({ foo: "<button>" });

console.log( document.body.innerHTML ); // <i><button></i>


We use ngProp to modify element's properties


<el data-ng-prop="expression => propertyName:string, expression => value:boolean|string" />

// Can be applied multiple times on element
<el data-ng-prop-0="..." data-ng-prop-9="..." />


(new NgTemplate( document.body , `<button data-ng-prop="'disabled', isDisabled"></button>` ))
  .sync({ isDisabled: true });

console.log( document.body.innerHTML ); // <button disabled=""></button>


We use ngAttr to modify element's attributes


<el data-ng-attr="expression => attrName:string, expression => value:boolean|string" />

// Can be applied multiple times on element
<el data-ng-attr-0="..." data-ng-attr-9="..." />


(new NgTemplate( document.body , `<input data-ng-prop="'required', required">` ))
  .sync({ required: true });

console.log( document.body.innerHTML ); // <input required="true">


We use ngData to modify element's dataset


<el data-ng-data="expression => datasetKey:string, expression => datasetValue:string" />

// Can be applied multiple times on element
<el data-ng-data-0="..." data-ng-data-9="..." />


(new NgTemplate( document.body , `<div data-ng-data="'dateOfBirth', value"></div>` ))
  .sync({ value: "1960-10-03" });

console.log( document.body.innerHTML ); // <div data-date-of-birth="1960-10-03"></div>


We use ngClass to modify element's classList


<el data-ng-class="expression => className:string, expression => toggle:boolean" />

// Can be applied multiple times on element
<el data-ng-class-0="..." data-ng-class-9="..." />


(new NgTemplate( document.body , `<i data-ng-class="'is-hidden', isHidden"></i>` ))
  .sync({ isHidden: true });

console.log( document.body.innerHTML ); // <i class="is-hidden"></i>
(new NgTemplate( document.body , `<i data-ng-class="className, isHidden"></i>` ))
  .sync({ isHidden: true, className: "is-hidden" });

console.log( document.body.innerHTML ); // <i class="is-hidden"></i>


We use ngFor to toggle visibility of an element (subtree) within the DOM


<el data-ng-if="expression => condition:boolean" />


let template = new NgTemplate( document.body , `<i data-ng-if="toggle">Hello!</i>` );

template.sync({ toggle: false });
console.log( document.body.innerHTML ); // <ng style="display: none; "></ng>

template.sync({ toggle: true });
console.log( document.body.innerHTML ); // <i>Hello!</i>


We use ngFor when we need to generate a list of elements (subtrees)
ngFor treats the generated list gracefully. It tries to maintain the nodes once appended to the DOM on list data change. However of removing rows from the list during synchronization ngFor can do it only if a unique row id property provided. Otherwise it updates the list


<el data-ng-for="let variable of expression => list:any[]" />


(new NgTemplate( document.body , `<i data-ng-for="let row of rows" data-ng-text="row"></i>` ))
  .sync({ rows: [ "foo", "bar" ] });

console.log( document.body.innerHTML ); // <i>foo</i><i>bar</i>


We use ngSwitch when we need to display on element (subtree) of a set of available options.


<el data-ng-switch="expression => variable:string|number">
  <el data-ng-switch-case="expression => value:string|number" />
  <el data-ng-switch-default />


(new NgTemplate( document.body ,
  `<div data-ng-switch="theCase">
    <i data-ng-switch-case="1">FOO</i>
    <i data-ng-switch-case="2">BAR</i>
  </div>` ))
  .sync({ theCase: 1 });

console.log( document.body.innerHTML ); // <i>FOO</i>

(new NgTemplate( document.body ,
  `<div data-ng-switch="theCase">
    <i data-ng-switch-case="1">FOO</i>
    <i data-ng-switch-case="2">BAR</i>
    <i data-ng-switch-case-default>BAZ</i>
  </div>` ))
  .sync({ theCase: 100 });

console.log( document.body.innerHTML ); // <i>BAZ</i>


We use ngEl to modify element properties
:exclamation: NOTE: Using ngEl is rather discouraging as it cannot be cached and every model sync will
cause the DOM modification even if the expression of ngEl wasn't changed


<el data-ng-el="expression => eval:void" />


(new NgTemplate( document.body , `<i data-ng-el="this.className = class"></i>` ))
  .sync({ class: "is-hidden" });

console.log( document.body.innerHTML ); // <i class="is-hidden"></i>

<i data-ng-el="this.textNode ="></i>
<i data-ng-el="this.setAttribute( 'name', )"></i>
<i data-ng-el="this.disabled = state.isVisible"></i>
<i data-ng-el="this.classList.toggle('name',"></i>


ngTemplate welcomes maintainers. There is plenty of work to do. No big commitment required, if all you do is review a single Pull Request, you are a maintainer.

How to build

This source code is written in TypeScript. In order to build the app simply run tsc in the root directory

How to test

There two options. You can run unit-tests in the console:
npm run test
or you can fire up tests/index.html in a browser