Reference

Component Bundles

To create a component, create a folder that bundles your component’s files. A component folder (bundle) must live in a parent folder that defines the component's namespace. The name of the parent folder is the namespace.

A bundle can be a UI component, which renders UI, or a module, which is a library used to share code.

Tip

To understand the structure of a component and its namespace, look at the lwc-recipes-oss repo. Most components are in the recipe namespace. There are also components in the ui namespace and the data namespace. Most components are UI components. To see an example of a module, see mortgage.

UI Components

The easiest way to create a UI component is to use the Lightning Web Components CLI, which generates boilerplate files.

A component that renders UI must have an HTML template file and a JavaScript class file. It may include a CSS file, additional JavaScript utility files, and test files. The HTML template, JavaScript class, and CSS file must have the same name. The framework uses the name to autowire the relationship between them.

mynamespace
    └──myComponent
        ├──__tests__
        |       └──myComponent.test.js
        ├──myComponent.html
        ├──myComponent.js
        ├──shareCode.js
        └──myComponent.css

The folder and its files must follow these naming rules.

Important

Use camel case to name your component. Camel case component folder names map to kebab case in markup. Every component is part of a namespace. Use a hyphen character (-) to separate the namespace from the component name. In markup, to reference a component in the example namespace with the name myComponent, use <example-my-component>.

<template>
    <example-my-component></example-my-component>
</template>

A bit more information about naming. Lightning web components match web standards wherever possible. The HTML standard requires that custom element names contain a hyphen. You can use underscores in component folder names, but they don’t map to kebab case in markup. The names are legal because the namespace is separated with a hyphen, but most developers expect hyphens instead of underscores in a web component name. For example, the component <example-my_component> is legal, but it looks odd and may confuse developers consuming your component.

Note

The HTML spec mandates that tags for custom elements (components) aren’t self-closing. Self-closing tags end with />. Therefore, <example-my-component> includes a closing </example-my-component> tag.

HTML File

Every UI component must have an HTML file with the root tag <template>.

The HTML file follows the naming convention <component>.html, such as myComponent.html.

Create the HTML for a Lightning web component declaratively, within the <template> tag. The HTML template element contains your component’s HTML.

<!-- myComponent.html -->
<template>
    <!-- Your markup here -->
</template>

When a component renders, the <template> tag is replaced with the namespace and name of the component. If this component were in the example namespace, the tag is <example-my-component>.

To create your template, use these techniques:

JavaScript File

Every UI component must have a JavaScript file, which is a class that defines the HTML element.

The JavaScript file follows the naming convention <component>.js, such as myComponent.js.

This class must include at least this code:

import { LightningElement } from 'lwc';
    export default class MyComponent extends LightningElement {

}

The core module is lwc. The import statement imports LightningElement from the lwc module. LightningElement is a custom wrapper of the standard HTML element.

The convention is for the class name to be Pascal Case, where the first letter of each word is capitalized. For myComponent.js, the class name is MyComponent.

Extend LightningElement to create a JavaScript class for a Lightning web component. The export default keywords export a MyComponent class for other components to use.

JavaScript files in Lightning web components are ES6 modules. By default, everything declared in a module is local—it’s scoped to the module.

The JavaScript class can contain:

In addition to this JavaScript file that creates the HTML element, a UI component’s folder can contain other JavaScript files that are used to share code. These utility JavaScript files must be ES6 modules and must have names that are unique within the component’s folder.

See Reactive Properties and Properties and Attributes.

CSS File

A component can include a CSS file. Use standard CSS syntax to style Lightning web components.

To style a component, create a style sheet in the component bundle with the same name as the component. If the component is called myComponent, the style sheet is myComponent.css. The style sheet is applied automatically.

See CSS.

Test Files

To create Jest tests for a component, create a folder called __tests__ at the top level of the component’s folder. Save the tests inside the __tests__ folder.

Jest runs JavaScript files in the __tests__ directory. Test files must have names that end in .js, and we recommend that tests end in .test.js. You can have a single test file with all of your component tests, or you can have multiple files to organize related tests. Test files can be placed in sub folders.

See Unit Tests.

Modules

To share code between components, create an ES6 module and export the variables or functions that you want to expose.

mynamespace
    └──myLibrary
        └──myLibrary.js

The module folder and file name must follow the same naming conventions as a UI component.

An ES6 module is a file that explicitly exports functionality that other modules can use. Modules make it easier to structure your code without polluting the global scope.

Within a JavaScript class, to reference a module, use namespace/module. The forward slash character (/) separates the namespace from the module name.

import { LightningElement } from 'lwc';

import { NamedExport } from 'acme/myLibrary';
import DefaultExport from 'acme/myLibrary';

export default class Example extends LightningElement {

}

See Share JavaScript Code.

JavaScript Decorators

Decorators add functionality to a property or function. The ability to create decorators is part of ECMAScript, but these decorators are unique to Lightning Web Components.

@api

To expose a public property, decorate it with @api. Public properties define the API for a component. To communicate down the component hierarchy, an owner component can access and set a child component’s public properties.

Public properties are reactive. If the value of a reactive property changes, the component’s template renders any content that references the property. For more information, see Public Properties.

To expose a public method, decorate it with @api. Public methods also define the API for a component. To communicate down the component hierarchy, owner and parent components can call JavaScript methods on child components.

Tip

To communicate down the containment hierarchy, use properties. To communicate up the containment hierarchy, fire an event in a child component and handle it in an owner or container component. See Events.

@track

To track a private property’s value and re-render a component when it changes, decorate the property with @track. Tracked properties are also called private reactive properties.

See Tracked Properties.

HTML Template Directives

Write templates using standard HTML and a few directives that are unique to Lightning Web Components. Directives are special HTML attributes that add dynamic behavior to an HTML template. Directives give you more power to manipulate the DOM in markup.

These are the directives supported in Lightning Web Components templates.

for:each={array}

Use this directive to iterate over an array and render a list.

See Render Lists.

for:index="index"

Use this directive to access the current item's zero-based index.

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

See Render Lists.

if:true|false={expression}

Use this directive to conditionally render DOM elements in a template.

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.

See Render DOM Elements Conditionally.

iterator:iteratorName={array}

Use this directive to apply special behavior to the first or last item in an array and render a list.

Access these properties on the iteratorName:

See Render Lists.

key={uniqueId}

Use this directive to improve rendering performance by assigning a unique identifier to each item in a list. 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.

lwc:dom="manual"

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.

See Third Party JavaScript Libraries.