Lightning Components Developer Guide

What is the Lightning Component Framework?
Quick Start
Creating Components
Using Components
Communicating with Events
Creating Apps
App Overview
Designing App UI
Creating App Templates
Content Security Policy Overview
Styling Apps
Using JavaScript
JavaScript Cookbook
Detecting Data Changes
Finding Components by ID
Dynamically Creating Components
Dynamically Adding Event Handlers
Dynamically Showing or Hiding Markup
Adding and Removing Styles
Which Button Was Pressed?
Using Apex
Controlling Access
Using Object-Oriented Development
Caching with Storage Service
Using the AppCache
Distributing Applications and Components
Debugging
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Dynamically Creating Components

Create a component dynamically in your client-side JavaScript code by using the $A.createComponent() method.

Use createComponent() instead of the deprecated newComponent(), newComponentAsync(), and newComponentDeprecated() methods.

Note

The syntax is:

1createComponent(String type, Object attributes, function callback)
  1. type—The type of component to create; for example, "ui:button"
  2. attributes—A map of attributes for the component, including the local Id (aura:id)
  3. callback—The callback to invoke after the component is created. The new component is passed in to the callback as a parameter

Let’s add a dynamically created button to this sample component.

1<!--c:createComponent-->
2<aura:component>
3    <aura:handler name="init" value="{!this}" action="{!c.doInit}"/>
4
5    <p>Dynamically created button</p>
6    {!v.body}
7
8</aura:component>

The client-side controller calls $A.createComponent() to create the button with a local ID and a handler for the press event. The button is appended to the body of c:createComponent.

1/*createComponentController.js*/
2({
3    doInit : function(cmp) {
4        $A.createComponent(
5            "ui:button",
6            {
7                "aura:id": "findableAuraId",
8                "label": "Press Me",
9                "press": cmp.getReference("c.handlePress")
10            },
11            function(newButton){
12                //Add the new button to the body array
13                if (cmp.isValid()) {
14                    var body = cmp.get("v.body");
15                    body.push(newButton);
16                    cmp.set("v.body", body);
17                }
18            }
19        );
20    },
21
22    handlePress : function(cmp) {
23        console.log("button pressed");
24    }
25})

c:createComponent contains a {!v.body} expression. When you use cmp.set("v.body", ...) to set the component body, you must explicitly include {!v.body} in your component markup.

Note

To retrieve the new button you created, use body[0].
1var newbody = cmp.get("v.body");
2var newCmp = newbody[0].find("findableAuraId");

Creating Nested Components

To dynamically create a component in the body of another component, use $A.createComponents() to create the components. In the function callback, nest the components by setting the inner component in the body of the outer component. This example creates a ui:outputText component in the body of a ui:message component.

1$A.createComponents([
2    ["ui:message",{
3        "title" : "Sample Thrown Error",
4        "severity" : "error",
5    }],
6    ["ui:outputText",{
7        "value" : e.message
8    }]
9    ],
10    function(components, status){
11        if (status === "SUCCESS") {
12            var message = components[0];
13            var outputText = components[1];
14            // set the body of the ui:message to be the ui:outputText
15            message.set("v.body", outputText);
16        }
17    }
18);

Destroying Dynamically Created Components

After a component that is declared in markup is no longer in use, the framework automatically destroys it and frees up its memory.

If you create a component dynamically in JavaScript and that component isn't added to a facet (v.body or another attribute of type Aura.Component[]), you have to destroy it manually using Component.destroy() to avoid memory leaks.

Declaring Dependencies

The framework automatically tracks dependencies between definitions, such as components. However, some dependencies aren't easily discoverable by the framework; for example, if you dynamically create a component that is not directly referenced in the component's markup. To tell the framework about such a dynamic dependency, use the <aura:dependency> tag. This ensures that the component and its dependencies are sent to the client, when needed.

Server-Side Dependencies

The createComponent() method supports both client-side and server-side component creation. If no server-side dependencies are found, this method is run synchronously. The top-level component determines whether a server request is necessary for component creation.

Creating components where the top-level components don't have server dependencies but nested inner components do is not currently supported.

Note

A server-side controller is not a server-side dependency for component creation as controller actions are only called after the component has been created.

A component with server-side dependencies is created on the server, even if it's preloaded. If there are no server dependencies and the definition already exists on the client via preloading or declared dependencies, no server call is made. To force a server request, set the forceServer parameter to true.