What is renderJS?

renderJS is a JavaScript library which helps modularizing your HTML5 code and your JavaScript applications. It uses the HTML5 standard as an easy way to specify self-contained components which consist of HTML5 code, CSS code and Javascript code. It helps reusing components in different applications just as easily as linking an HTML5 page to another. It also helps combining multiple reusable component within the same single page application.

The main focus of renderJS is graphic user interface (GUI) components such as editors, viewers, fields or widgets. renderJS can also be used to define reusable components with no GUI such as translators or format converters.

A Simple Example

Let us suppose we want to add a text editor to an HTML5 page, here is how we proceed:

<!DOCTYPE html>
    <title>Simple example</title>
    <script src="RSVP.js"></script>
    <script src="render.js"></script>
    <p>Text editor displays below:</p>
    <div data-gadget-url="http://www.renderjs.org/editor/rtl/index.html"></div>

renderJS takes care of managing all dependencies and rendering.

Getting started

This walkthrough is designed to get you started using a basic renderJS instance.

Download renderJS library, renderJS core as well as the dependencies required to start using core components.





The renderJS library



A custom version of RSVP to add cancellation support


Add the renderJS script to your HTML head:

    <script src="RSVP.js"></script>
    <script src="render.js"></script>

renderJS fundamentals

renderJS can be used either by adding HTML5 tags to your page or by invoking Javascript methods.

The renderJS script provides HTML5 attributes which can be added to any HTML5 page.


Sample Call



<div data-gadget-url="hello-world.html"></div>

Embeds the HTML5 code of a gadget in a page, loads CSS and Javascript depencies.


<div data-gadget-url="hello-layout.html" data-gadget-scope="hello"></div>

Associates a gadget to a namespace which can later be used to retrieve a gadget programmatically


<div data-gadget-url="hello-layout.html" data-gadget-sandbox="iframe"></div>

Defines the sandboxing type of a gadget (iframe, public, etc.).

The renderJS Javascript API replicates and extends HTML5 attibutes.








Get the currently loading gadget class (based on the HTML URL).


callback function with one parameter representing the gadget instance

GadgetKlass (to allow method chaining)

Declares an init function called at the gadget instance creation.


  • method name
  • method callback

GadgetKlass (to allow method chaining)

Declares a public asynchronous method of a gadget.


service callback

GadgetKlass (to allow method chaining)

Declares an asynchronous callback executed when a gadget is included into the DOM.


  • acquisition name
  • acquisition callback

GadgetKlass (to allow method chaining)

Declares an asynchronous acquisition callback.


  • method name
  • acquisition name

GadgetKlass (to allow method chaining)

Declares an asynchronous method to acquire method from parent.



Returns the DOM element used by the gadget


  • gadget url
  • gadget options


Returns a newly created subgadget


gadget scope


Returns a previously created subgadget


gadget scope


Drop a reference to a previously created subgadget

Design of the renderJS application

A full renderJS application is a composition of multiple gadgets rendered in the same page. More than this, a gadget URL can be rendered simultaneously inside the page.

In order to achieve a working state, the gadget code should strictly follow some rules:

  • Never access the DOM globally. A gadget should not have any knowledge of its current parent gadget. Instead, only on local DOM element (gadget.getElement())
  • Do not use HTML ID attribute, or it will prevent multiple gadget instanciations. Instead, use class attribute.
  • Do not access page URL. Instead, uses parameters provided to method call (like render)
  • A gadget can only call methods of its direct children. A child can not call a method of its parent. Instead, it should acquire a method.
  • Do not break the promise chain. If the RSVP.Queue's "push" method is used instead of the "then" method, your application will have an automatic code cancellation for free (on page change for example).
  • Do not catch all errors. Propagate not handled errors instead, so that application errors could be reported to the user/developper.

renderJS inter gadget communication is always asynchronous. Promise pattern is used to simplify the code and error handling. Take a coffee, and read the specifications.

Step by step tutorials

Follow this tutorial.

Supported browsers

RenderJs work in any standards compliant browser. It has been successfully tested with Firefox and Chrome. Current considered "stable" version is 0.7.3 which can be downloaded from link below: http://git.erp5.org/gitweb/renderjs.git/blob_plain/HEAD:/dist/renderjs-latest.js?js=1

Applications using RenderJs

RenderJs has been successfully used for by ERP5, OfficeJs and SANEF.


RESILIENCE W3C Lightning Talk or download as PDF.


  > git clone https://git.erp5.org/repos/renderjs.git

  > npm install

  > grunt server
Submit patches to renderJS forum.


  • Ivan Tyagov
  • Jean-Paul Smets
  • Sven Franck
  • Romain Courteaud

Copyright and license

renderJS is an open-source library and is licensed under the LGPL license. More information on LGPL can be found here

Add new tab

Tab name: