HTML rendering with conditionals, loops, data binding, components, slots, and pipes. Works on the server and in the browser.
Zero dependencies. Tiny footprint, only 6kb gzipped.
Use normal .html files, syntax is W3C standards compatible, no extra tooling required.
npm i @nodedk/render
Compile once and reuse the function with different data:
var render = require('@nodedk/render')
var template = render.compile('<h1 text="title"></h1>')
var html = template({ title: 'Hello & welcome' })
// <h1>Hello & welcome</h1>
Pass shared variables through the data option when compiling:
var data = { site: { name: 'My site' } }
var template = render.compile('<h1 text="site.name"></h1>', { data })
template() // <h1>My site</h1>
// Render data overrides shared values
template({ site: { name: 'Another site' } }) // <h1>Another site</h1>
template({ site: null }) // <h1></h1>
template({ site: undefined }) // <h1></h1>
// Shared changes apply to later renders
data.site.name = 'Updated site'
template() // <h1>Updated site</h1>
Components use shared data unless overridden by props:
<template is="site-header">
<h1 text="site.name"></h1>
</template>
<!-- Uses shared site.name -->
<site-header></site-header>
<!-- Pass render data explicitly to use it in a component -->
<site-header :site="site"></site-header>
<!-- Overrides shared site.name -->
<site-header :site="{name: 'Component site'}"></site-header>
text escapes values; raw inserts HTML unchanged:
<h1 text="title"></h1>
<!-- Tag forms leave no wrapper; null and undefined become empty text -->
<p>Hello <text value="user.name"></text>!</p>
<div raw="body"></div>
<raw value="body"></raw>
Prefix attributes with : to evaluate and escape their values:
<!-- Null and undefined omit the attribute -->
<a :href="url" text="label"></a>
<img :src="image.url" :alt="image.description">
<!-- Boolean attributes appear only when truthy -->
<button :disabled="busy">Save</button>
<div :class="active ? 'active' : 'idle'"></div>
Use if for conditions, of for arrays, and in for objects:
<p if="available">In stock</p>
<p if="!available">Sold out</p>
<!-- Loop variables take precedence; for runs before if -->
<ul>
<li for="item, index of items" if="item.visible">
<text value="index"></text>: <text value="item.name"></text>
</li>
</ul>
<div for="value, key in settings">
<text value="key"></text>: <text value="value"></text>
</div>
Define components at the top level; attributes pass strings and : passes data:
<template is="card">
<article>
<!-- Access props directly by name -->
<h2 text="title"></h2>
<!-- Fallback when no default slot is supplied -->
<slot>Default body</slot>
<footer><slot name="footer"></slot></footer>
</article>
</template>
<card :title="product.name">
<!-- Default slot: reads caller data, then shared defaults -->
<p text="description"></p>
<!-- Named slot: assign a direct child -->
<button slot="footer">Buy</button>
</card>
Pass separate definitions through components:
var template = render.compile('<card :title="title"></card>', {
components: [
'<template is="card"><h2 text="title"></h2></template>'
]
})
Pass an object with props (no : prefix):
<template is="card">
<h2 text="title"></h2>
<p text="description"></p>
</template>
<!-- Explicit attributes win in either order; product stays unchanged -->
<card props="product" title="Featured"></card>
<card title="Featured" props="product"></card>
<card props="{title: 'Featured', description: product.description}"></card>
Declare optional prop types on a component template:
<template is="card" name="string" age="number" active="boolean" data="object" items="array">
<h2 text="name"></h2>
<p text="age"></p>
</template>
<card name="Ada" age="42" active="true" data='{"id":1}' items="[2,3]"></card>
<!-- Explicit age wins, then converts to number 43 -->
<card props="{name: 'Ada', age: '42'}" :age="43"></card>
<!-- Missing or null props use defaults; objects and arrays get fresh defaults -->
<card></card>
| Type | Conversion | Default |
|---|---|---|
string |
JavaScript String(value) |
'' |
number |
JavaScript Number(value); NaN falls back to 0 |
0 |
boolean |
JavaScript truthiness, except 'false' and '0' become false |
false |
object |
Parse JSON strings; accept non-array objects | Fresh {} |
array |
Parse JSON strings; accept arrays | Fresh [] |
| Supported | Syntax |
|---|---|
| Values | Strings, decimal numbers, true, false, null, undefined |
| Arrays and objects | [1, 2, 3], {name: user.name, labels: ['a', 'b'],} |
| Property access | user.name, items[0], settings[key] |
| Arithmetic | +, -, *, /, %, parentheses |
| Comparisons | ==, !=, ===, !==, <, <=, >, >= |
| Logic | !, &&, ||, ??, condition ? yes : no |
Use expressions in bindings, including nested arrays and objects:
<template is="user-list">
<ul if="settings.visible">
<li for="user of users" text="user.name ?? 'Anonymous'"></li>
</ul>
</template>
<user-list :settings="{visible: true}" :users="[{name: name}, {name: 'Grace'}]"></user-list>
Register functions as pipes; they run left to right with the value first:
var template = render.compile('<p text="title | truncate(limit) | uppercase"></p>', {
pipes: {
truncate: (value, length) => value.slice(0, length),
uppercase: value => value.toUpperCase()
}
})
template({ title: 'Hello world', limit: 5 })
// <p>HELLO</p>
<!-- Pipes have lowest precedence; use parentheses within expressions -->
<p text="compact ? (title | truncate(30)) : title"></p>
<!-- Use pipes instead of function or method calls -->
<p text="title | uppercase"></p>
. reads literal inner HTML without evaluating its directives:
<h2 text=". | truncate(30) | uppercase">Hello world</h2>
<!-- Displays the strong tags as text -->
<div text=".">Hello <strong>world</strong></div>
<!-- Preserves the strong tags as HTML -->
<div raw=".">Hello <strong>world</strong></div>
TL;DR: For the 1,000-item workload below, @nodedk/render renders approximately 75% faster than EJS, 85% faster than React, 136% faster than Handlebars, and 161% faster than Mustache, measured as renders per second.
Times are in microseconds (µs); lower is faster.
| Engine | Compile | Render 10 items | Render 100 items | Render 1,000 items |
|---|---|---|---|---|
| @nodedk/render | 11.21 | 3.12 | 29.01 | 283.61 |
| EJS | 11.65 | 5.36 | 49.23 | 495.52 |
| React | 326.90 | 6.38 | 51.69 | 524.24 |
| Handlebars | 120.25 | 7.54 | 67.88 | 669.18 |
| Mustache | 5.38 | 8.17 | 74.37 | 740.32 |
The bundle size is only 6kb gzipped including the compiler and parser.
npm test
Created by Vidar Eldøy