Dynamically Creating Components

Create a component dynamically in your client-side JavaScript code by using the $A.createComponent() method. To create multiple components, use $A.createComponents().
Note

Note

Use $A.createComponent() instead of the deprecated $A.newCmp() and $A.newCmpAsync() methods.

The syntax is:

$A.createComponent(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(cmp, status, errorMessage)—The callback to invoke after the component is created. The callback has three parameters.
    1. cmp—The component that was created. This enables you to do something with the new component, such as add it to the body of the component that creates it. If there’s an error, cmp is null.
    2. status—The status of the call. The possible values are SUCCESS, INCOMPLETE, or ERROR. Always check that the status is SUCCESS before you try to use the component.
    3. errorMessage—The error message if the status is ERROR.

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

<!--c:createComponent-->
<aura:component>
    <aura:handler name="init" value="{!this}" action="{!c.doInit}"/>

    <p>Dynamically created button</p>
    {!v.body}
</aura:component>

The client-side controller calls $A.createComponent() to create a ui:button with a local ID and a handler for the press event. The function(newButton, ...) callback appends the button to the body of c:createComponent. The newButton that’s dynamically created by $A.createComponent() is passed as the first argument to the callback.

/*createComponentController.js*/
({
    doInit : function(cmp) {
        $A.createComponent(
            "lightning:button",
            {
                "aura:id": "findableAuraId",
                "label": "Press Me",
                "onclick": cmp.getReference("c.handlePress")
            },
            function(newButton, status, errorMessage){
                //Add the new button to the body array
                if (status === "SUCCESS") {
                    var body = cmp.get("v.body");
                    body.push(newButton);
                    cmp.set("v.body", body);
                }
                else if (status === "INCOMPLETE") {
                    console.log("No response from server or client is offline.")
                    // Show offline error
                }
                else if (status === "ERROR") {
                    console.log("Error: " + errorMessage);
                    // Show error message
                }
            }
        );
    },

    handlePress : function(cmp) {
        console.log("button pressed");
    }
})
Note

Note

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.

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.

$A.createComponents([
    ["ui:message",{
        "title" : "Sample Thrown Error",
        "severity" : "error",
    }],
    ["ui:outputText",{
        "value" : e.message
    }]
    ],
    function(components, status, errorMessage){
        if (status === "SUCCESS") {
            var message = components[0];
            var outputText = components[1];
            // set the body of the ui:message to be the ui:outputText
            message.set("v.body", outputText);
        }
        else if (status === "INCOMPLETE") {
            console.log("No response from server or client is offline.")
            // Show offline error
        }
        else if (status === "ERROR") {
            console.log("Error: " + errorMessage);
            // Show error message
        }
    }
);

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.

Avoiding a Server Trip

The createComponent() and createComponents() methods support both client-side and server-side component creation. For performance and other reasons, client-side creation is preferred. If no server-side dependencies are found, the methods are executed client-side. The top-level component determines whether a server request is necessary for component creation.

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

A component with server-side dependencies must be created on the server. Server-side dependencies include dynamically created component definitions, dynamically loaded labels, and other elements that can’t be predetermined by static markup analysis.
Note

Note

A server-side controller isn’t a server-side dependency for component creation because controller actions are only called after the component has been created.

A single call to createComponent() or createComponents() can result in many components being created. The call creates the requested component and all its child components. In addition to performance considerations, server-side component creation has a limit of 10,000 components that can be created in a single request. If you hit this limit, ensure you’re explicitly declaring component dependencies with the <aura:dependency> tag or otherwise pre-loading dependent elements, so that your component can be created on the client side instead.

There’s no limit on component creation on the client side.

Note

Note

Creating components where the top-level components don’t have server dependencies but nested inner components do isn’t currently supported.