Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Lightning Web Components

Lightning Web Components: Your First Component

Learn Lightning Web Components: the bundle files, HTML templates, lwc:if, for:each, public properties with @api and the meta XML, with a runnable JavaScript template stand-in.

Lightning Web Components (LWC) is Salesforce's UI framework for building pages in Lightning Experience, Experience Cloud sites and the mobile app. It is built on web standards: ES modules, custom elements and shadow DOM. If you know modern JavaScript and HTML, you already know most of it. Apex runs on the server and LWC runs in the browser; later lessons connect them (calling Apex from LWC).

LWC needs the Salesforce platform and its compiler, so it cannot run on this site. The LWC listings below are read-only. The runnable examples are plain JavaScript stand-ins that model what the framework does for you (templates, loops, conditionals), clearly labelled.

What a component looks like

A component is a folder inside force-app/main/default/lwc. For a component named accountCard you create:

Text
accountCard/
  accountCard.html        the template
  accountCard.js          the JavaScript class
  accountCard.css         optional styles (scoped to the component)
  accountCard.js-meta.xml where it can be placed, API version

The folder name is camelCase; in a template other components use it as <c-account-card> (kebab-case with the c namespace prefix).

accountCard.html

HTML
<template>
  <lightning-card title="Account" icon-name="standard:account">
    <div class="slds-p-around_medium">
      <p>Name: {name}</p>
      <p>Employees: {employees}</p>
    </div>
  </lightning-card>
</template>

accountCard.js

JavaScript
import { LightningElement, api } from 'lwc';

export default class AccountCard extends LightningElement {
    @api name = 'Acme';
    employees = 120;
}

accountCard.js-meta.xml

XML
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>62.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
  </targets>
</LightningComponentBundle>

isExposed and targets make the component available in Lightning App Builder. Without them it can still be used inside other components, but admins cannot drop it on a page.

Curly braces bind a JavaScript property to the template. Only simple property paths are allowed: no expressions such as {a + b}. For a computed value, write a getter in the class.

JavaScript
get greeting() {
    return `Hello, ${this.name}`;
}

and use in the template.

Conditional rendering

Use lwc:if, lwc:elseif and lwc:else (the older if:true and if:false still work):

HTML
<template>
  <template lwc:if={isLarge}>
    <p>Large account</p>
  </template>
  <template lwc:else>
    <p>Small account</p>
  </template>
</template>
JavaScript
get isLarge() {
    return this.employees > 500;
}

Lists with for:each

HTML
<template>
  <ul>
    <template for:each={contacts} for:item="contact">
      <li key={contact.Id}>{contact.Name}</li>
    </template>
  </ul>
</template>

Every element produced by a loop needs a key with a unique, stable value, normally a record Id. The alternative is iterator:it={contacts}, which also gives you first and last flags.

Public properties with @api

@api exposes a property or method so a parent can set it:

HTML
<c-account-card name="Globex"></c-account-card>

A parent sets attributes in kebab-case (account-name) for a property named accountName. A component must not change its own @api properties; they belong to the parent. If you need to modify one, copy it into a private field.

Try the idea: a template and key (JavaScript stand-in)

This is not LWC: it is a few lines of plain JavaScript showing the same idea, where a template is a function of the component's properties.

JS Stand-in: a template function and for:each (JavaScript)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In LWC the framework re-runs the equivalent of render for you whenever a tracked value changes. You only write the template and the properties.

Try the idea: child properties (JavaScript stand-in)

JS Stand-in: a parent sets a child's public property (JavaScript)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Styling and the shadow DOM

CSS in accountCard.css applies only inside the component thanks to the shadow DOM (synthetic shadow in most Salesforce contexts). That keeps styles from leaking, but it means you cannot style a child's internals directly. Salesforce provides the Lightning Design System classes (slds-*) and styling hooks (CSS variables) for consistent looks.

Where to put the component

After deploying (see deployment), open Lightning App Builder, edit a page, and drag accountCard from Custom components onto the canvas. The VS Code Salesforce extensions can also preview it from a local server.

flowchart LR
    A["accountCard.html"] --> D["Component"]
    B["accountCard.js"] --> D
    C["accountCard.css"] --> D
    E["js-meta.xml"] -->|"where it can be used"| D

A component is four files that the platform compiles into one custom element.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How is a component named accountCard written in another component's template?

    Template tags use kebab-case with the c namespace prefix. The c:accountCard form is Aura syntax.
  2. 2. Why does every item in a for:each loop need a key?

    A unique, stable key lets the renderer update the right DOM elements efficiently.
  3. 3. What does @api do on a property?

    @api marks a property or method as public API of the component.
  4. 4. Can you write {a + b} inside a template?

    Templates bind only to properties or getters; computation belongs in the class.

Summary

  • A component is an HTML template, a JavaScript class, optional CSS and a meta XML file.
  • Bind with ; compute with getters; show or hide with lwc:if; loop with for:each and a key.
  • @api makes a property public; the child must not modify it.
  • Styles are scoped to the component; use SLDS classes and styling hooks.

Next: LWC Reactivity, Events and Communication