node package manager



dependency status

browser support

Populate DOM elements with data

Populate has two APIs you can use. Either the Schema api or the bind API. The Schema api allows you define a schema representation of how you will populate a group of DOM elements with data.

The bind API allows you to embed the Schema into the DOM as data-bind attributes and uses the Schema API internally

Schema example

The idea is that you take a pair of data and DOM elements and apply a mapping from the data onto the DOM.

<div id="my-template">
    <span data-marker="text"></span>
    <a data-marker="link"> some link! </a>
var Schema = require("populate/render")
var unpack = require("unpack-element")
var populate = Schema({
    text: "textContent"
    , link: "href"
var elements = unpack(document.getElementById("my-template").cloneNode(true))
    text: "some text goes in span!"
    , link: ""
}, elements)

The above mapping placed the link into the <a>'s href property and placed the text into the <span>'s textContent.

bind example

The idea with bind is that you just bind data onto a root Element and it will go and parse out all of the data-bind attributes

<div id="my-template">
    <span data-bind="text"></span>
    <a data-bind="href:link"> some link! </a>
var bind = require("populate/bind")
var rootElem = document.getElementById("my-template").cloneNode(true)
    text: "some text goes in span!"
    , link: ""
}, elements)

Complex Example

The format of an object of elements allows you to populate multiple elements from a single object of data.

It also works cleanly with the result of unpack-html. However using unpack-html is completely optional. Feel free to get references to your DOM elements however you want!

<!-- ./template.html -->
    <div data-bind="someText"></div>
        <a data-bind="href:someLink, text:someText"></a>
        <textarea data-bind="value:nested.value"></textarea>
    <ul data-marker="name">
        <li>I'm a nested template or something</li>
var html = require("unpack-html")
var bind = require("populate/bind")
var template = require("./template.html")
// Generate an object of DOM element references to populate 
// You can use something other then unpack-html! 
var elements = html(template)
var data = {
    someText: "this is some text"
    , someLink: ""
    , nested: {
        value: "you can render nested things"
    , name: [
        , "two"
        , "three"
bind(data, elements, {
    // Custom logic. Mappings are just functions, do anything 
    // you want! 
    name: function (value, elem) {
        var tmpl = elem.firstElementChild
        value.forEach(function (text) {
            var clone = tmpl.cloneNode(true)
            clone.textContent = text


  • uses functions and recursions so is both modular and composable
  • optionally use data binding in your template
  • Works nicely with reducibles


npm install populate


  • Raynos

MIT Licenced