Create a Custom Renderer

Base Component Rendering

The base component in the framework is aura:component. Every component extends this base component.

The renderer for aura:component is in componentRenderer.js. This renderer has base implementations for the four phases of the rendering and rerendering cycles:

• render()
• rerender()
• afterRender()
• unrender()

The framework calls these functions as part of the rendering and rerendering lifecycles and we will learn more about them soon. You can override the base rendering functions in a custom renderer.

Rendering Lifecycle

The rendering lifecycle happens once in the lifetime of a component unless the component gets explicitly unrendered. When you create a component:

1. The framework fires an init event, enabling you to update a component or fire an event after component construction but before rendering.
2. The render() method is called to render the component’s body.
3. The afterRender() method is called to enable you to interact with the DOM tree after the framework’s rendering service has inserted DOM elements.
4. The framework fires a render event, enabling you to interact with the DOM tree after the framework’s rendering service has inserted DOM elements. Handling the render event is preferred to creating a custom renderer and overriding afterRender().

Rerendering Lifecycle

The rerendering lifecycle automatically handles rerendering of components whenever the underlying data changes. Here is a typical sequence.

1. A browser event triggers one or more Lightning events.
2. Each Lightning event triggers one or more actions that can update data. The updated data can fire more events.
3. The rendering service tracks the stack of events that are fired.
4. The framework rerenders all the components that own modified data by calling each component’s rerender() method.
5. The framework fires a render event, enabling you to interact with the DOM tree after the framework rerenders a component. Handling the render event is preferred to creating a custom renderer and overriding rerender().

The component rerendering lifecycle repeats whenever the underlying data changes as long as the component is valid and not explicitly unrendered.

For more information, see Events Fired During the Rendering Lifecycle.

Custom Renderer

You don’t normally have to write a custom renderer, but it’s useful when you want to interact with the DOM tree after the framework’s rendering service has inserted DOM elements. If you want to customize rendering behavior and you can’t do it in markup or by using the init event, you can create a client-side renderer.

A renderer file is part of the component bundle and is auto-wired if you follow the naming convention, <componentName>Renderer.js. For example, the renderer for sample.cmp would be in sampleRenderer.js.

Customize Component Rendering

Customize rendering by creating a render() function in your component’s renderer to override the base render() function, which updates the DOM.

The render() function returns a DOM node, an array of DOM nodes, or nothing. The base HTML component expects DOM nodes when it renders a component.

You generally want to extend default rendering by calling superRender() from your render() function before you add your custom rendering code. Calling superRender() creates the DOM nodes specified in the markup.

This code outlines a custom render() function.

render : function(cmp, helper) {
    var ret = this.superRender();
    // do custom rendering here
    return ret;
},

Rerender Components

When an event is fired, it may trigger actions to change data and call rerender() on affected components. The rerender() function enables components to update themselves based on updates to other components since they were last rendered. This function doesn’t return a value.

If you update data in a component, the framework automatically calls rerender().

You generally want to extend default rerendering by calling superRerender() from your renderer() function before you add your custom rerendering code. Calling superRerender() chains the rerendering to the components in the body attribute.

This code outlines a custom rerender() function.

rerender : function(cmp, helper){
    this.superRerender();
    // do custom rerendering here
}

Access the DOM After Rendering

The afterRender() function enables you to interact with the DOM tree after the framework’s rendering service has inserted DOM elements. It’s not necessarily the final call in the rendering lifecycle; it’s simply called after render() and it doesn’t return a value.

You generally want to extend default after rendering by calling superAfterRender() function before you add your custom code.

This code outlines a custom afterRender() function.

afterRender: function (component, helper) {
    this.superAfterRender();
    // interact with the DOM here
},

Unrender Components

The base unrender() function deletes all the DOM nodes rendered by a component’s render() function. It is called by the framework when a component is being destroyed. Customize this behavior by overriding unrender() in your component’s renderer. This method can be useful when you are working with third-party libraries that are not native to the framework.

You generally want to extend default unrendering by calling superUnrender() from your unrender() function before you add your custom code.

This code outlines a custom unrender() function.

unrender: function () {
    this.superUnrender();
    // do custom unrendering here
}