Lightning Web Components

A component that renders UI has an HTML template file and a JavaScript class file, which is an ES module.

The power of Lightning Web Components is the templating system, which uses the virtual DOM to render components smartly and efficiently. Use simple syntax to declaratively bind a component’s template to data in the component’s JavaScript class.

A template is valid HTML with a <template> root tag. Write templates using standard HTML and a few directives that are unique to Lightning Web Components. Directives are special HTML attributes, like if:true and for:each, that give you more power to manipulate the DOM in markup.

Let Lightning Web Components manipulate the DOM instead of writing JavaScript to do it.

Data Binding

To bind a property in a component’s template to a property in the component’s JavaScript class, in the template, surround the property with curly braces: {property}.

Here’s the simplest example of data binding. The name property in the template is bound to the name property in the JavaScript class.

In helloWorld.js, change the value of World! and you’ll see the component update.

To see the power of data binding, add another property in helloWorld.js.

In helloWorld.html, add {announcement}.

The property in { } must be a valid JavaScript identifier or member expression. For example, {data} and {} are both valid. Don’t add spaces around the property, for example, { data } is not valid HTML. It’s illegal to compute a value in an expression, like data[2].name['John']. To compute a value, use a getter.

The @api decorator makes the name property public so that other components can set it. If we remove @api, the property still binds to the HTML template, but it’s private. To see for yourself, remove @api in the playground. When the value of name changes, the component re-renders.

This code is standard HTML and JavaScript. The only feature in this code that’s exclusive to Lightning Web Components is the @api decorator.


Before we go further, it’s important to understand naming. A component’s folder and file names are camel case, helloWorld, helloWorld.html, and helloWorld.css. In HTML markup, camelCase maps to kebab-case. When a component renders, the <template> tag is replaced with <namespace-component-name>. The tag includes the component’s namespace. For example, a component with the template helloWorld.html in the example namespace renders as <example-hello-world>. For more information about naming, see Component Bundles.

Handle User Input

This component has an input field that asks for a name to greet. When the value of the input field changes, the component changes the value of the bound name property.

Type something in the input field to see the recipe in action.

The <input> element uses the oninput event to listen for a change to its value. To bind the handleInput function to the template, we use the same syntax that we use to bind a property, {...}. The handleInput JavaScript function executes when the value of the <input> element changes.

When the value of the name property changes, the component re-renders.

We talk about event handling in-depth in another topic, but notice in helloBinding.js that handleInput is passed an event object. The event object contains information about the input event. The component uses the event object to get the value that the user enters into the input field.


In LWC versions 1.1.0 and higher, properties that contain a primitive value are reactive. If a reactive property is used in a template and its value changes, the component re-renders.

Use Getters to Compute a Value

To dynamically compute a value for a property used in a template, define a JavaScript getter that computes the value.

Getters are much more powerful than computing values in template expressions because they’re JavaScript functions and can contain any code that’s legal in a function. Getters also enable unit testing, which reduces bugs and the pain of debugging.

When a component renders, all the expressions used in the template are evaluated, which means that getters are invoked.

This example takes two variables, firstName and lastName, concatenates them, and converts them to uppercase.

Render Lists

To render a list of items, use for:each directive or the iterator directive to iterate over an array.

The iterator directive has first and last properties that let you apply special behaviors to the first and last items in an array.

Regardless of which directive you use, you must use a key directive to assign a unique ID to each item. When a list changes, the framework uses the key to re-render only the item that changed. The key in the template is used for performance optimization and isn’t reflected in the DOM at run time.

This code you write to render lists is standard HTML and JavaScript, except for the directives, which are exclusive to Lightning Web Components.


To render an array, add the for:each={array} directive to a nested <template> tag that encloses the HTML elements you want to repeat. To access the current item, use for:item="currentItem". To access the current item’s index, use for:index="index".

Every item in a list must have a key. To assign a key to every element in the list, use the key={uniqueId} directive.

This example iterates over an array called contacts, which is defined in the component’s JavaScript class.


Every item in a list must have a key. When a list changes, the framework uses the key to identify each item so that it can re-render only the item that changed. The key must be a string or a number, it can’t be an object. You can’t use index as a value for key. Assign unique keys to an incoming data set. To add new items to a data set, use a private property to track and generate keys. Use this code pattern.


To apply a special behavior to the first or last item in a list, use the iterator directive, iterator:iteratorName={array}. Add the iterator directive to a nested <template> tag that encloses the HTML elements you want to repeat.

Use iteratorName to access these properties:

  • value—The value of the item in the list. Use this property to access the properties of the array. For example, iteratorName.value.propertyName.
  • index—The index of the item in the list.
  • first—A boolean value indicating whether this item is the first item in the list.
  • last—A boolean value indicating whether this item is the last item in the list.

This sample code uses the same array as the previous example. To apply special rendering to the first and last items in the list, the code uses the first and last properties with the if:true directive.

If the item is first in the list, the <div> tag renders with the styling defined in the CSS list-first class. If the item is last in the list, the <div> tag renders with the styling defined in the CSS list-last class.


To access the value of a property in the array, use iteratorName.value.propertyName, not iteratorName.propertyName. For example, in helloIterator.html, look at {it.value.Name} and {it.value.Title}.

Render HTML Conditionally

To render HTML conditionally, add the if:true|false={property} directive to a <template> tag that encloses the conditional content.

The directive binds property to the template and removes and inserts DOM elements based on whether property is a truthy or falsy value.

This simple example component has a property called isTemplateOne. The component has two templates. Only one renders depending on the value of isTemplateOne.

To change which template renders, change the value of isTemplateOne to true in the component’s JavaScript class.

Notice that the JavaScript doesn’t manipulate the DOM, it simply changes the value of a property.

Render Multiple Templates

You may want to render a component with more than one look and feel, but not want to mix the HTML in one file. For example, one version of the component is plain, and another version displays an image and extra text. In this case, you can import multiple HTML templates and write business logic that renders them conditionally. This pattern is similar to the code splitting used in some JavaScript frameworks.

Create multiple HTML files in the component bundle. Import them all and add a condition in the render() method to return the correct template depending on the component’s state.

The returned value from the render() method must be a template reference, which is the imported default export from an HTML file. In this example, the template references are templateOne and templateTwo.

To reference CSS from an extra template, the CSS filename must match the filename of the extra template. For example, the template templateOne.html can reference CSS only from templateOne.css. It can’t reference CSS from multipleTemplates.css.


It’s rare to define render() in a component. It’s more common to use an if:true|false directive to render nested templates conditionally.

Import a Component Dynamically

To import a component at run time, see lwc:dynamic.

← InstallationES Modules →

Scroll to Top