Mount selected element as a Sparky template.

Sparky('#id', data);

Mount selected element as a template and render it immediately using data as scope.

var sparky = Sparky('#id');

The constructor returns a sparky object that is both an array-like object of DOM nodes and a pushable stream of data.



Push data into sparky to be rendered as template scope on the next animation frame.


Unmount the template, disconnecting its tags from scope updates. Tags and nodes are left in the DOM in their stopped state.

Tip: you could remove them with sparky.forEach(dom.remove).


Call fn after sparky is stopped.



Sparky is in one of two states: "active" or "done".

Sparky templates

Sparky templates are made of plain old HTML enhanced with functions and tags.


The import function imports 'package.json' and pushes it into scope, then Sparky takes the 'version' property, prepends it with 'v' and replaces the tag with the text. The result?

Latest: {[version|prepend:'v']}


Functions, declared in the sparky-fn attribute, are run before the template is mounted. They have two parts, a name followed by 0 or more parameters.

Functions are view-controllers with responsibility for getting data and spitting out scopes, and can listen to and mutate nodes. They're powerful. You're going to want to write your own. But first, let's have a look at some built-ins.

Getting scope

We have already seen the import function in action. load also loads data, but with a subtle difference: where import makes a single request and creates a single data object (per url), distributing it to other imports, load makes makes a new request and creates a new data object each time.

The find function takes a JS path (in dot notation) and looks for data at that path in the global object (window).

The get function takes a JS path and looks for data at that path in the current scope.

Composing templates

Sparky has a function for cloning and inserting a template into a node: the template function. It performs the import only when the first scope is available, so it can be used to provide initial content.

Looping over arrays

The third function worth a special mention is each. It copies and remounts the node for each object found in scope, where scope must be an array or array-like.





Where scope is an array or array-like, duplicates the element for each object in scope.

<ul sparky-fn="import:example.json">
<li sparky-fn=" each">{[name]}</li>
  • {[name]}


Get an object from path in the global scope (window) and push it to the template scope.

<pre sparky-fn="global:location">
href: {[href]}
href: {[href]}


Gets the value of path of the current scope.

<pre sparky-fn="import:example.json[0]">
name: {[name]}
id: {[id]}
name: {[name]}
id:   {[id]}


Looks in the object cache for data for that url, or loads JSON data from the url and caches it, pushing that data to the template scope.


Replaces the content of the element with the cloned, mounted content of the template referenced by url. Usually this is a hashref for a <template id="ref"> in the same document. Sparky will also import the contents of other elements or elements in external documents.

Note that the initial content of the element is left untouched until the template has data and is ready to render.

<pre sparky-fn="import:package.json template:#example-template">
<template id="example-template">
My name is {[title]} and I'm {[version]}!


For debugging. Logs node and scopes to the console.


Sends a request on form submit, where the type of request is determined by the current state of the method attribute and the URL determined by the action attribute of the form. The JSON data payload is the current scope.


Calls .preventDefault() on events of type.


Stops sparkifying the element. No more functions are run, and the contents of the element are not parsed.

Use stop to ignore blocks of static HTML inside a Sparky template.


Tags, found in the attributes and content of the node and its descendants, are rendered with values from the scope.


A tag may have three parts. A path, followed by any number of pipe-seperated transfoms and their parameters.



Get property name from value.


Returns the result of invoking method name with params on an object.


Returns the (boolean) result of a strict equality check between n and value.


Returns typeof value.


Maps array using transform name with arguments.


Filters array using transform name with arguments.


Appends string to value.


Converts value to lowercase.


Returns result of matching value against regex.


Tests value against regex.


Appends string to value to output a string of length n.


Prepends string to value to output a string of length n.


Prepends string to value.


Outputs slug of value.


Looks up value in Sparky.translations and outputs it. If a translation does not exist, warns the console and outputs the original value.


Converts value to uppercase.


Converts value to decibels.


Converts a numeric value from radians to degrees.


Converts numeric values in the range 0-1 to the range min-max.

See also normalise:min,max.


Converts numeric values to strings with n decimal places.


Given a number of coordinates of the form [x, y], performs linear interpolation to transform input (x) values to output (y) values.


Returns localised number string with n decimal places.


Converts numeric values in the range min-max to the range 0-1.

See also denormalise:min,max.


Takes a number and outputs str1 or str2 depending on whether that number is considered plural in lang. Currently there are 4 languages supported out-of-the-box – EN, DE, FR, IT – but it is easy to add more.


Maps either JSON date strings or JS date objects to human-readable date strings in a format defined by format, where format describes the output in a Django/PHP-style date format strings.

Deprecated, will remain supported as an add-on.


Maps either JSON date strings or JS date objects to human-readable date strings in a format defined by format


Converts Date, ISO8601 date string or UNIX time (in seconds) to string in format.


Converts ISO time string, a number (in seconds) or the UTC time values of a Date object to string in format.


Returns value1 where value is truthy, otherwise value2.

Sparky options


A string that names the fn attribute. The default is 'sparky-fn'.


A string that prefixes attributes where Sparky looks for tags. The default is 'sparky-'.

Sparky looks for tags in prefixed attributes before trying unprefixed attributes. There are three main cases where this is useful:

  • In IE, where Sparky cannot mount the style attribute (because IE does not provide access to the original text of the attribute), use sparky-style.
  • For the value attribute, where you don't want to interfere with the browser's autocompletion or default values, use :value.
  • Where you want to provide different html content to browsers that fail to run Sparky.