Lightning Aura Components Developer Guide
jSummer '26 (API version 67.0)
Spring '26 (API version 66.0)
Winter '26 (API version 65.0)
Summer '25 (API version 64.0)
Spring '25 (API version 63.0)
Winter '25 (API version 62.0)
Summer '24 (API version 61.0)
Spring '24 (API version 60.0)
Winter '24 (API version 59.0)
Summer '23 (API version 58.0)
Spring '23 (API version 57.0)
Winter '23 (API version 56.0)
Summer '22 (API version 55.0)
Spring '22 (API version 54.0)
Winter '22 (API version 53.0)
Summer '21 (API version 52.0)
Spring '21 (API version 51.0)
Winter '21 (API version 50.0)
Summer '20 (API version 49.0)
Spring '20 (API version 48.0)
Winter '20 (API version 47.0)
Summer '19 (API version 46.0)
Spring '19 (API version 45.0)
Winter '19 (API version 44.0)
Summer '18 (API version 43.0)
Spring '18 (API version 42.0)
Winter '18 (API version 41.0)
Summer '17 (API version 40.0)
Spring '17 (API version 39.0)
Winter '17 (API version 38.0)
Summer '16 (API version 37.0)
Spring '16 (API version 36.0)
Winter '16 (API version 35.0)
Summer '15 (API version 34.0)
Spring '15 (API version 33.0)
Winter '15 (API version 32.0)
Developing Secure Code
Supported JavaScript
Invoking Actions on Component Initialization
Sharing JavaScript Code in a Component Bundle
Sharing JavaScript Code Across Components
Using External JavaScript Libraries
Dynamically Creating Components
Detecting Data Changes with Change Handlers
Finding Components by ID
Working with Attribute Values in JavaScript
Working with a Component Body in JavaScript
Working with Events in JavaScript
Checking Component Validity
Modifying Components Outside the Framework Lifecycle
Throwing and Handling Errors
Dynamically Adding Event Handlers To a Component
Dynamically Showing or Hiding Markup
Adding and Removing Styles
Which Button Was Pressed?
Formatting Dates in JavaScript
Using JavaScript Promises
Making API Calls from Components
Testing Components
Using JavaScript
Use JavaScript for client-side code. The $A
namespace is the entry point for using the framework in JavaScript code.
For all the methods available in $A, see the JavaScript API.
A component bundle can contain JavaScript code in a client-side controller, helper, or renderer. Client-side controllers are the most commonly used of these JavaScript resources.
Expressions in JavaScript Code
In JavaScript, use string syntax to evaluate an expression. For example, this expression retrieves the label attribute in a component.
1var theLabel = cmp.get("v.label");Only use the {! } expression syntax in markup in .app or .cmp resources.
Note
-
Supported JavaScript
The Aura Components programming model supports ES5 syntax and ES6 Promises. -
Invoking Actions on Component Initialization
Use the init event to initialize a component or fire an event after component construction but before rendering. -
Sharing JavaScript Code in a Component Bundle
Put functions that you want to reuse in the component’s helper. Helper functions also enable specialization of tasks, such as processing data and queueing server-side actions. Helper functions are local to a component, improve code reuse, and move the heavy lifting of JavaScript logic away from the client-side controller, where possible. -
Sharing JavaScript Code Across Components
You can build simple Lightning components that are entirely self-contained. However, if you build more complex applications, you probably want to share code, or even client-side data, between components. -
Using External JavaScript Libraries
To reference a JavaScript library, upload it as a static resource and use a <ltng:require> tag in your .cmp or .app markup. -
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(). -
Detecting Data Changes with Change Handlers
Configure a component to automatically invoke a change handler, which is a client-side controller action, when a value in one of the component's attributes changes. -
Finding Components by ID
Retrieve a component by its ID in JavaScript code. -
Working with Attribute Values in JavaScript
These common patterns are useful for working with attribute values in JavaScript. -
Working with a Component Body in JavaScript
These are useful and common patterns for working with a component’s body in JavaScript. -
Working with Events in JavaScript
These are useful and common patterns for working with events in JavaScript. -
Modifying the DOM
The Document Object Model (DOM) is the language-independent model for representing and interacting with objects in HTML and XML documents. It’s important to know how to modify the DOM safely so that the framework’s rendering service doesn’t stomp on your changes and give you unexpected results. -
Checking Component Validity
If you navigate elsewhere in the UI while asynchronous code is executing, the framework unrenders and destroys the component that made the asynchronous request. You can still have a reference to that component, but it is no longer valid. The cmp.isValid() call returns false for an invalid component. -
Modifying Components Outside the Framework Lifecycle
Use $A.getCallback() to wrap any code that modifies a component outside the normal rerendering lifecycle, such as in a setTimeout() call. The $A.getCallback() call ensures that the framework rerenders the modified component and processes any enqueued actions. -
Throwing and Handling Errors
The framework gives you flexibility in handling unrecoverable and recoverable app errors in JavaScript code. For example, you can throw these errors in a callback when handling an error in a server-side response. -
Calling Component Methods
Use <aura:method> to define a method as part of a component's API. This enables you to directly call a method in a component’s client-side controller instead of firing and handling a component event. Using <aura:method> simplifies the code needed for a parent component to call a method on a child component that it contains. -
Dynamically Adding Event Handlers To a Component
You can dynamically add a handler for an event that a component fires. -
Dynamically Showing or Hiding Markup
You can use CSS to toggle markup visibility. However, <aura:if> is the preferred approach because it defers the creation and rendering of the enclosed element tree until needed. -
Adding and Removing Styles
You can add or remove a CSS style on a component or element during runtime. -
Which Button Was Pressed?
To find out which button was pressed in a component containing multiple buttons, use Component.getLocalId(). -
Formatting Dates in JavaScript
The AuraLocalizationService JavaScript API provides methods for formatting and localizing dates. -
Using JavaScript Promises
You can use ES6 Promises in JavaScript code. Promises can simplify code that handles the success or failure of asynchronous calls, or code that chains together multiple asynchronous calls. -
Making API Calls from Components
By default, you can’t make calls to third-party APIs from client-side code. Add a remote site as a Trusted URL with Content Security Policy (CSP) directives to allow client-side component code to load assets from and make API requests to that site’s domain.