HTML Template Directives

A directive is a special attribute that adds dynamic behavior to an HTML template. You can use certain directives on a root <template> tag, a nested <template> tag, or an HTML element such as a <p> tag. Some directives are supported for use with different tags.

A root <template> tag is the first element in a component's HTML template. It supports the following directives.

Preserves HTML comments so that they are rendered in the DOM. For example, you can use conditional comments to improve design and styling in specific browsers.

When lwc:preserve-comments is enabled, you can’t place comments between sibling conditional directives.

Renders a component using light DOM, which enables third-party tools to traverse the DOM using standard browser query APIs such as querySelector.

A component's template can include nested <template> tags with certain directives. These nested tags support only the following directives.

Iterates over an array and renders a list. for:each={array} can be used with nested templates and HTML elements. See Render Lists.

Accesses the current item.

The currentItem placeholder is an identifier that the model injects into the current scope.

Accesses the current item's zero-based index.

The index placeholder is a new identifier that the model injects into the current scope.

Deprecated. The if:true and if:false directives are no longer recommended. They may be deprecated and removed in the future. Use lwc:if, lwc:elseif, and lwc:else instead.

if:true|false={expression} conditionally renders DOM elements in a template, calling the expression for each of if:true and if:false. In cases where you chain if:true and if:false directives, they are not as performant nor as lightweight as the lwc:if, lwc:elseif, and lwc:else directives. See Render DOM Elements Conditionally.

The expression can be a JavaScript identifier (for example, person) or dot notation that accesses a property from an object (person.firstName). The engine doesn’t allow computed expressions (person[2].name['John']). To compute the value of expression, use a getter in the JavaScript class.

Conditionally render DOM elements in a template. lwc:if, lwc:elseif, and lwc:else supersede the if:true and if:false directives.

Use the conditional directives on nested <template> tags, <div> tags or other HTML elements, and on your custom components tags like <c-custom-cmp>.

Both lwc:elseif and lwc:else must be immediately preceded by a sibling lwc:if or lwc:elseif.

Both lwc:if and lwc:elseif must evaluate an expression. However, lwc:else must not have an attribute value.

The expression passed in to lwc:if and lwc:elseif supports simple dot notation. Complex expressions like !condition, object?.property?.condition or sum % 2 === 1 aren't supported. To compute such expressions, use a getter in the JavaScript class.

You can't precede lwc:elseif or lwc:else with text or another element. Whitespace is ignored between the tags when the whitespace is a sibling of the conditional directive. For example you can't have a <div> tag that comes after lwc:if and before lwc:else.

Code comments can be included as a sibling of the conditional directive only if lwc:preserve-comments isn't enabled.

To check for a falsy, pass in the negation operator in your getter's return value so the expression is true.

Applies special behavior to the first or last item in an array and renders a list. iterator:iteratorname={array} can be used with nested templates and HTML elements. iteratorname must be lowercase. See Render Lists.

Accesses these properties on the iteratorname:

• 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.

Links the scoped slot fragment in a parent component to the lwc:slot-bind directive in a child component. The child component must use light DOM.

Add lwc:slot-data to the <template> element in the parent component and set the value of lwc:slot-data to a string literal.

The <template lwc:slot-data> element must be a direct child of a custom element. For example, the <template lwc:slot-data> element is nested in the custom element <c-child>.

The string literal for lwc:slot-data and the variable used by the corresponding lwc:slot-bind don’t have to share the same name.

A <template> element can have only one instance of lwc:slot-data. A scoped slot fragment binds to only one child component.

A <slot> tag supports the following directives.

This directive binds data to the scoped slot in a child component. The child component must use light DOM.

Add lwc:slot-bind to the <slot> element of the child component and set the value of lwc:slot-bind to a variable name.

The <slot lwc:slot-bind> element can only be used in a light DOM element’s HTML <template>.

You can add only one instance of lwc:slot-bind to a <slot> element. A scoped slot can bind to only one source of data.

You can use certain directives on an HTML element, such as on a <p> tag, a base component, or your own custom component.

The lwc:if, lwc:elseif, and lwc:else directives in the previous section are also supported for use with HTML tags, a base component, or your own custom component.

Iterates over an array and renders a list, using for:item={currentItem} and for:index={index}. Also supported for use with nested templates, as described in the previous section.

Applies special behavior to the first or last item in an array and renders a list. Also supported for use with nested templates, as described in the previous section.

Improves rendering performance by assigning a unique identifier to each item in a list. Use this directive with iterator:iteratorname={array} or for:each={array}.

The key must be a string or a number, it can’t be an object. The engine uses the keys to determine which items have changed. See Render Lists.

Add this directive to a native HTML element to call appendChild() on the element from the owner’s JavaScript class and preserve styling.

If a call to appendChild() manipulates the DOM, styling isn’t applied to the appended element. Using JavaScript to manipulate the DOM isn’t recommended when programming Lightning web components, but some third-party JavaScript libraries require it.

Enables a third-party web component or custom element to be rendered as a native web component in an LWC template. See Third-Party Web Components (Beta).

Refs locate DOM elements without a selector and query elements in a specified template only.

To use refs, add the lwc:ref directive to your element and assign it a value. To call that reference, use this.refs. In this example, this.refs references the directive lwc:ref="myDiv" to access the <div> at runtime.

We recommend that you use this.refs instead of this.template.querySelector() in shadow DOM or this.querySelector() in light DOM. For shadow DOM components, this.refs refers to elements inside of the shadow DOM. For light DOM components, this.refs refers to elements inside of the light DOM. If lwc:ref is not defined in the template, then this.refs returns undefined.

See Access Elements the Component Owns.

Spreads properties to a child component, enabling elements to accept an object that’s bound as properties at runtime. Define your properties in your component's JavaScript.

Apply childProps as a property to the child component. Only one instance of lwc:spread on an element is allowed.

See Spread Properties on Child Components.

To instantiate a component dynamically, use the <lwc:component> managed element with the lwc:is directive in a component's HTML file.

Here's an HTML template that uses <lwc:component>.

For more information, see Dynamically Instantiate Components.

See Also

• Use HTML Templates
• Use Third-Party JavaScript Libraries