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="get:'' each">{[name]}</li>
  • {[name]}


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


Gets the value of path of the current scope.

<pre sparky-fn="import:'example.json' get:'[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.


Loads JSON data from url and pushes it to the template scope. A new data object is created per load request.


When scope is a string, replaces the content of the current element with scope by setting .innerHTML.


Replaces the content of the element with the cloned, mounted content of the element referenced by url. Usually this is a hashref for a <template> in the same document, but Sparky will also import the contents of nodes in external documents.

Note that the original content of the element is never mounted.


For debugging. Logs node and scopes to the console.


Posts the content of a form as JSON.


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.


Appends string to value.


Converts value to lowercase.


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.


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 or JSON time string to string in format.


Returns value1 where value is truthy, otherwise value2.