Initialisation Options

edit this page

The following is a complete list of initialisation options, with full descriptions below grouped by category.

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
css templating component only css to include on render
data data the data to bind to the template
debug environment increases app feedback
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
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
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 an element whose ID is myTemplate:

template: '#myTemplate'

See the 60 second setup for an example of this.

Please note that while Ractive will fetch any element by ID and use its content as the template, browsers may escape the contents of tags like <div> when initially rendered, leading to unexpected results in your template.

The <script> tag is a good option as browsers will not modify the contents and is the canonical way to include inline Ractive templates in the document. However, make sure to set type='text/ractive' or the browser will try and execute the contents as javascript and you'll get an exception.

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"/>), and value is a is a decorator functions. See Decorators for more info.

decorators: {
    'myDomponent': 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')

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 Array or String

The data with which to initialise.

// object
data: { foo: 'bar' }

// array
data: [ 'red', 'blue', 'yellow' ]

// string
data: 'foo'

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. 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 true. 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.

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 ) {...}
}

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

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>

Environment

debug Boolean

Defaults to false. Increases the severity of response to unexpected events or unfound resources to help debug applications. Generally will throw errors or print console messages when otherwise things would print a console messages or fail silently.

// throws when 'myPartial' not found:
template: '<p>{{>myPartial}}</p>',
debug: true