Initialisation Options

The following is an exhaustive list of initialisation options that you can pass to new Ractive(options), with full descriptions grouped below by category.

Note that any additional options will be added as properties of the instance, so you can create custom methods (e.g. for calling from templates):

var ractive = new Ractive({
  myMethod: function () {
    alert( 'my method was called' );
  }
});
ractive.myMethod(); // triggers the alert
Option Category Description
adapt data adaptors to use
adaptors data registry of available adaptors
append placement how to handle existing content in the dom
complete transitions fine-tune template placement in the dom
components templating components to include for use by the template
computed data computed properties to include
csp parsing output CSP compatible (inline functions for expressions) templates
css templating component only css to include on render
data data the data to bind to the template
decorators templating decorators to include for use by the template
delimiters parsing delimiters to use when parsing the template
easing transitions easing functions to use in transitions
el placement render to this element in the dom
enhance placement try to reuse existing DOM on intial render
events templating events to include for use by the template
interpolators transitions interpolators to use for animating values
isolated data prevent components from accessing parent data and registries
lazy binding don't bind to every keypress
magic binding data object getters and setters that update view
modifyArrays binding array modification methods update the view
noCssTransform templating prevent transformation of component css
noIntro transitions do not apply transitions on render
onchange lifecycle events event fired when data changes
oncomplete lifecycle events event fired once transitions have completed
onconfig lifecycle events event fired once all configuration options have been processed
onconstruct lifecycle events event fired immediately after new Ractive(...)
ondetach lifecycle events event fired each time ractive.detach() is called
oninit lifecycle events event fired when the instance is ready to be rendered
oninsert lifecycle events event fired each time ractive.insert() is called
onrender lifecycle events event fired each time the instance is rendered
onteardown lifecycle events event fired each time the instance is destroyed
onunrender lifecycle events event fired each time the instance is unrendered
onupdate lifecycle events event fired after ractive.update() is called
partials templating partials to include for use by the template
preserveWhitespace parsing don't normalize template whitespace
sanitize parsing remove designated elements and event attributes
staticDelimiters parsing one-time binding parsing delimiters
staticTripleDelimiters parsing one-time binding non-escaped parsing delimiters
stripComments parsing remove HTML comments from templates
template templating specifies the template to use
transitions transitions transitions to include for use by the template
transitionsEnabled transitions allow transitions
tripleDelimiters parsing non-escaped parsing delimiters
twoway binding prevent updates from the view back to the model

Templating

template String or (if preparsing) Array or Object

The template to use. If this is a string, it must be valid (if meaningless, until rendered) HTML:

template: '<p>{{greeting}} world!</p>',

Otherwise this must be the output of ractive.parse(), usually precompiled for use in the browser:

template: parsedTemplates.foo,

Or alternatively, you can pass an id selector string like #myTemplate - in this case, Ractive will use the contents of a <script> tag whose ID is myTemplate:

template: '#myTemplate'

See the 60 second setup for an example of this.

Make sure to set type='text/ractive' on the <script> tag or the browser will try and execute the contents as javascript and you'll get an exception. Some text editors will highlight type='text/html' as HTML, which can be useful and the browser will still ignore it for execution.

If a function, the result of the function can be a string or a pre-parsed template.

partials Object

A key: value hash of partials that are specific to this instance, where key is the name of the partial (as referenced within templates as {{>myPartial}}), and value is either a valid template string or the output of ractive.parse().

partials: {
    myPartial: "<p>I'm a partial!<p>"
}

The partial name used in the template can also be used to lookup the partial by ID. See Partials for more info.

components Object

A key: value hash of components that are specific to this instance, where key is the name of the component (as referenced within templates as <my-component></my-component>), and value is a valid component created by Ractive.extend().

components: {
    'my-component': Ractive.extend({
        template: '#componentTemplate',
        init: function () {...}
    })
}

See Components for more info.

decorators Object

A key: value hash of decorators that are specific to this instance, where key is the name of the decorator (as referenced within templates as <div decorator="myDecorator"></div>), and value is a is a decorator functions. See Decorators for more info.

decorators: {
    'myDecorator': function( node, fire) {...}
}

events Object

A key: value hash of event plugins that are specific to this instance, where key is the name of the event (as referenced within templates as <button on-mycustomevent="fire"></button>), and value is the custom event plugin functions. See Writing event plugins for more info.

events: {
    'mycustomevent': function( node, fire) {...}
}

css String

Used on components to specify css styles to be inserted into the document.

noCSSTransform Boolean

Defaults to false. Prevents component css from being transformed with scoping guids.

DOM Placement

el String or HTMLElement or jQuery-like collection

Directives for the element to render to. Use append option (see below) to control whether existing content is replaced.

  • string id or selector, see valid selectors
    el: '#container'
  • HTMLElement DOM element
    el: document.body
  • any obj where obj[0] is an HTMLElement, see jquery collections
    el: $('#container')

enhance Boolean

Defaults to false. Whether or not to try to reuse the existing DOM in the target element when rendering a.k.a. progressive enhancement. This allows you to serve the fully rendered page and then render the Ractive template at load over the pre-rendered page without completely wiping out the existing content. There are a few limitations surrounding text nodes, but all matching elements will be reused.

This option cannot be used with append.

To expand on the limitations with text nodes, since HTML does not have a markup representation for individual adjacent text nodes where the DOM does, the loaded DOM will have all text nodes merged when the document loads from the server. Ractive needs individual adjacent text nodes in certain situations like outer text {{#if foo}}inner text{{/if}}. The 'outer text ' text node is always present, and if foo becomes truthy, an additional text node will be inserted next to the 'outer text ' node containing 'inner text'. It has been suggested that Ractive could also deal with merged text nodes, but that would become quite complex because there are certain scenarios where a text node would have to split and be rejoined as the model changed e.g. outer text {{#if foo}}<span>hello</span>{{/if}} the other side. In that case, if foo is initially falsey, the 'outer text ' and ' the other side' nodes could be merged into a single node. However, if foo became truthy, that node would have to be split into two to place on either side of the <span>.

Additionally, unescaped HTML mustaches (triples) don't play nicely with enhance because there's no easy way to match up the string content to the target DOM nodes. This may be remedied at some point in the future.

append Boolean or anchor

Defaults to false. Controls whether existing content is replace and optionally where to place the rendered content.

  • false - rendered content replaces any existing contents of el
      // dom
  <div id='container'><p>existing content</p></div>
      // options
  el: '#container',
  append: false, //default
  template: '<p>new content</p>'
      // result
  <div id='container'><p>new content</p></div>
  • true rendered content is appended to el
      // dom
  <div id='container'><p>existing content</p></div>
      // options
  el: '#container',
  append: true,
  template: '<p>new content</p>'
      // result
  <div id='container'><p>existing content</p><p>new content</p></div>
  • anchor is any valid option as specified in el that resolves to an HTMLElement. Rendered content is appended to el before anchor, see ractive.insert()
      // dom
  <div id='container'><p>red</p><p>blue</p><p>yellow</p></div>
      // options
  el: '#container',
  append: document.querySelector('p:nth-child(2)'),
  template: '<p>green</p>'
      // result
  <div id='container'><p>red</p><p>green</p><p>blue</p><p>yellow</p></div>

Data & Binding

data Object or Function

The data with which to initialise.

// object
data: { foo: 'bar' }
// function
data: function() {
  return { foo: 'bar' };
}

computed Object

An object that maps to a set of computed values.

computed: {
    area: '${width} * ${height}'
}

See Computed Properties for more information and examples .

magic Boolean

Defaults to false. Whether or not to wrap data in ES5 accessors for automatic binding (see magic mode).

var data = { foo: 'bar' };
new Ractive({ data: data } );
// will update automagically:
data.foo = 'fizz'

adapt Array

Custom wrappers to be used with all or part of the supplied data, see Adaptors. Unlike components or other registries where there is a template-level directive that informs Ractive that plugin is to be used, adaptors are a data-level construct and so you use the adapt option to tell Ractive which adaptors are to be used with that instance. If you define the adaptors directly on the instance or component, you do not need to specify them in the adapt option.

Can either be the adaptor itself, or the name of an adaptor registred via Ractive.adaptors:

Ractive.adaptors.myAdaptor = MyAdaptor1;
new Ractive({
   adapt: [ 'myAdaptor', MyAdaptor2 ]
}

adaptors Object

A key: value hash of adaptors that are specific to this instance. Usually the adapt property can directly specify which adaptors to use on this instance and the adaptors property is used to register an adaptor on components or Ractive.adaptors.

adaptors: {
    myAdaptor: MyAdaptor
}

modifyArrays Boolean

Defaults to false. Whether or not to modify array mutator methods to enable frictionless data binding with lists (see array modification).

var items = [ 'red', 'blue' ];
new Ractive({
    data: data,
    modifyArrays: true //default
} );
// will update automagically:
items.push( 'green' );

twoway Boolean

Defaults to true. Whether or not two-way data binding is enabled (see Two‐way binding).

var ractive = new Ractive({
    template: '<input value="{{foo}}">',
    data: { foo: 'bar' },
    twoway: false
});
// user types "fizz" into <input>, but data value is not changed:
console.log( ractive.get( 'foo' ) ); //logs "bar"
// updates from the model are still pushed to the view
ractive.set( 'foo', 'fizz' );
// input now displays "fizz"

Also see static delimiters for one-time binding

lazy Boolean

Defaults to false. If two-way data binding is enabled, whether to only update data based on text inputs on change and blur events, rather than any event (such as key events) that may result in new data.

var ractive = new Ractive({
    template: '<input value="{{foo}}">',
    data: { foo: 'bar' },
    lazy: true
});
// will not fire as user is typing
ractive.on('change', function(){
      // only happens on exiting <input> or return if submit
      console.log('changed!')
})

isolated Boolean

Defaults to false. This option is typically only relevant as an extension option for Components. Controls whether the component will look outside itself for data and registry items.

Lifecycle events

See the main entry for lifecycle events.

Transitions & Animations

transitions Object

A key: value hash of transitions that are specific to this instance. The key is referenced within templates using intro and outro attributes on elements, and value is a transition functions, see Transitions for more info.

template: '<p intro="slide" outro="slide">hello world</p>',
transitions: {
    slide: function ( t, params ) {...}
}

transitionsEnabled Boolean

Defaults to true. Whether or not transitions are enabled for this instance.

noIntro Boolean

Defaults to false. Whether or not to skip intro transitions on render.

var ractive = new Ractive({
    template: '<ul>{{#items}}<li intro="fade">{{.}}</li>{{/items}}</ul>',
       data: { items: [ 'red', 'blue' ] },
    transitions: { fade: function ( t, params ) {...} },
    noIntro: true
});
// 'red' and 'blue' list items do not fade in on intro
ractive.get('items').push( 'green' );
// 'green' list item will fade in

complete Function

A function that will be called when render is complete (i.e. all intro transitions have finished). If there are no intro transitions, this function will be called as soon as the instance is created)

template: '<p intro="fade">hello</p>',
transitions: { fade: function ( t, params ) {...} },
complete: function () {
    console.log( '<p> has completed fade in!' );
}

easing Object

A key: value hash of easing function. See Ractive.easing

interpolators Object

A key: value hash of interpolators use by ractive.animate()

Parsing

csp Boolean

Defaults to false. Whether or not to add inline functions for expressions after parsing. This can effectively eliminate eval caused by expressions in templates. It also makes the resulting template no longer JSON compatible, so the template will have to be served via script tag.

delimiters Array where [ open, close ]

Defaults to [ '{{', '}}' ]. Used to set what delimiters to use when parsing templates.

template: 'hello <%= world %>',
delimiters: [ '<%=', '%>' ],
data: { world: 'earth' }
// result:
hello earth

tripleDelimiters Array where [ open, close ]

Defaults to [ '{{{', '}}}' ]. Used to set what triple delimiters to use when parsing templates.

template: 'hello @html@',
tripleDelimiters: [ '@', '@' ],
data: { html: '<span>world</span>' }
// result:
hello <span>world</span>

staticDelimiters Array where [ open, close ]

Defaults to [ '[[', ']]' ]. Used to set what static (one-time binding) delimiters to use when parsing templates.

var ractive = new Ractive({
    template: 'hello [[foo]]',
    staticDelimiters: [ '[[', ']]' ], /default
      data: { foo: 'world' }
});
// result: "hello world"
ractive.set( 'foo', 'mars' );
// still is: "hello world"

staticTripleDelimiters Array where [ open, close ]

Defaults to [ '[[[', ']]]' ]. Used to set what static (one-time binding) triple delimiters to use when parsing templates.

var ractive = new Ractive({
    template: 'hello [[[html]]]',
    staticTripleDelimiters: [ '[[[', ']]]' ], /default
      data: { html: '<span>world</span>' }
});
// result: "hello <span>world</span>"
ractive.set( 'html', '<span>mars</span>' );
// still is: "hello world"

preserveWhitespace Boolean

Defaults to false. Whether or not to preserve whitespace in templates when parsing. (Whitespace in <pre> elements is always preserved.)

var ractive = new Ractive({
    template: '<p>hello\n\n  \tworld   </p>',
    preserveWhitespace: false //default
});
console.log( ractive.toHTML() );
// "<p>hello world</p>"
var ractive = new Ractive({
    template: '<p>hello\n\n  \tworld   </p>',
    preserveWhitespace: true
});
console.log( ractive.toHTML() );
// "<p>hello
     world   </p>"

Please note that the browser will still deal with whitespace in the normal fashion.

stripComments Boolean

Defaults to true. Whether or not to remove comments in templates when parsing.

template: '<!-- html comment -->hello world',
stripComments: false
// result:
<!-- html comment -->hello world

sanitize Boolean or Object

Defaults to false. If true, certain elements will be stripped from templates at parse time - <applet>, <base>, <basefont>, <body>, <frame>, <frameset>, <head>, <html>, <isindex>, <link>, <meta>, <noframes>, <noscript>, <object>, <param>, <script>, <style> and <title> - as will event attributes (e.g. onclick).

template: '<p>some content</p><frame>Am I a bad element or just misunderstood?</frame>',
sanitize: true
// result:
<p>some content</p>

Alternatively, pass in an object with an elements property containing an array of blacklisted elements, and an optional eventAttributes boolean (true means 'disallow event attributes').

template: '<p>some content</p><div onclick="doEvil()">the good stuff</div>',
sanitize: {
    elements: [ 'p' ],
    eventAttributes: true
}
// result:
<div>the good stuff</div>