Lightning Web Components —
Complete Tutorial & Practice Guide

1 What is a Lightning Web Component?

A Lightning Web Component (LWC) is a custom HTML element built with modern JavaScript on top of native Web Components browser standards — Custom Elements, Shadow DOM, HTML templates, and ES modules. Salesforce introduced LWC in 2019 as a faster, lighter-weight alternative to the older Aura framework, and it's now the recommended way to build custom UI on the Lightning Platform.

Because LWC compiles almost directly to standards-based browser APIs (rather than a large custom JavaScript runtime like Aura), components render faster, ship smaller bundles, and are easier to unit test with familiar tools like Jest. LWC and Aura components can coexist and even nest inside each other, which is why most orgs migrate incrementally rather than rewriting everything at once.

Where LWCs run

A single LWC can be dropped into several different contexts without changing its code:

• Lightning App Builder — as a component on a Record Page, App Page, Home Page, or inside a Lightning Community/Experience Cloud page.
• Lightning Record Pages — automatically receiving the current record's Id via a reserved @api recordId property.
• Utility bars, Quick Actions, and flow screens — as a Screen Flow component with input/output variables.
• Standalone LWC (Off-core) — Lightning Web Components can even run outside Salesforce entirely using the open-source LWC framework, though most Salesforce development targets the platform runtime.

2 Anatomy of an LWC

Every Lightning Web Component lives in its own folder and is made up of a small, fixed set of files that all share the component's name. At minimum you need an HTML file and a JavaScript file; the metadata file is required for the component to be usable anywhere in the org.

<template>
    <lightning-card title="Account Details" icon-name="standard:account">
        <div class="slds-p-horizontal_small">
            <p>{accountName}</p>
        </div>
    </lightning-card>
</template>

import { LightningElement, api } from 'lwc';

export default class AccountCard extends LightningElement {
    @api accountName;
}

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

3 Decorators: @api, @track, @wire

LWC uses three special decorators, imported from the lwc module, to control how data flows into, out of, and reactively through a component.

@api — public properties

A property marked @api can be set by whatever renders the component — a parent LWC's template, a Lightning Record Page, or a Flow Screen. On a Record Page, Salesforce automatically populates a reserved @api recordId property with the current record's Id, which is the standard way a component knows which record it's showing.

import { LightningElement, api } from 'lwc';

export default class ChildBadge extends LightningElement {
    @api label;   // set by the parent: <c-child-badge label="VIP"></c-child-badge>
}

@wire — declarative, reactive data

@wire is the idiomatic way to read data in LWC. You give it a wire adapter (or an Apex method) and it automatically calls it, re-calls it whenever any parameter changes, caches results client-side, and pushes the value/error into your component — no manual subscription or lifecycle management required.

import { LightningElement, wire } from 'lwc';
import { getRecord } from 'lightning/uiRecordApi';
import NAME_FIELD from '@salesforce/schema/Account.Name';

export default class AccountName extends LightningElement {
    @api recordId;

    // Property form — result lands directly on this.account
    @wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
    account;

    // Function form — gives you full control over the {data, error} shape
    @wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
    wiredAccount({ data, error }) {
        if (data) { this.accountName = data.fields.Name.value; }
        if (error) { console.error(error); }
    }
}

4 Lifecycle Hooks

Every LWC goes through a predictable lifecycle as it's inserted into and removed from the DOM. LWC exposes hooks — plain methods you can optionally implement — at each key stage.

5 Calling Apex from LWC

LWC talks to Apex through methods annotated @AuraEnabled. There are two calling styles, and choosing the right one matters for both performance and correctness.

Wire (reactive, cacheable reads)

Use @wire for read-only data. The Apex method must be static and annotated @AuraEnabled(cacheable=true) — this tells the Lightning Data Service it's safe to cache the result client-side and reuse it across components without hitting the server again.

public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactsByAccount(Id accountId) {
        return [
            SELECT Id, Name, Email
            FROM Contact
            WHERE AccountId = :accountId
            WITH SECURITY_ENFORCED
            LIMIT 50
        ];
    }
}

import getContactsByAccount from '@salesforce/apex/ContactController.getContactsByAccount';

@wire(getContactsByAccount, { accountId: '$recordId' })
contacts;

Imperative (writes, and anything not cacheable)

Any Apex method that performs DML — or one you need to invoke on-demand (e.g. from a button click) rather than automatically — must be called imperatively. Import the same method, but call it as a function returning a Promise instead of using @wire.

import createContact from '@salesforce/apex/ContactController.createContact';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

async handleSave() {
    try {
        await createContact({ accountId: this.recordId, lastName: this.lastName });
        this.dispatchEvent(new ShowToastEvent({
            title: 'Success', message: 'Contact created', variant: 'success'
        }));
    } catch (error) {
        this.dispatchEvent(new ShowToastEvent({
            title: 'Error creating contact',
            message: error.body?.message,
            variant: 'error'
        }));
    }
}

6 Custom Events & Component Communication

How components talk to each other depends entirely on their relationship in the component tree.

Parent → child: @api properties

The parent sets an @api property directly as an HTML attribute in its own template — no events needed for this direction.

<template>
    <c-child-badge label="VIP Customer"></c-child-badge>
</template>

Child → parent: CustomEvent

The child creates and dispatches a CustomEvent, optionally carrying a payload in detail. The parent listens using an on-prefixed attribute matching the event's name.

handleSelect(event) {
    const selectedEvent = new CustomEvent('select', {
        detail: { contactId: this.contact.Id }
    });
    this.dispatchEvent(selectedEvent);
}

<c-contact-row onselect={handleContactSelect}></c-contact-row>

handleContactSelect(event) {
    const contactId = event.detail.contactId;
}

Unrelated components: Lightning Message Service

LWC events do not bubble across the synthetic Shadow DOM boundary by default, so two sibling components — or components on entirely different parts of a page — cannot communicate with plain DOM events. For that, use Lightning Message Service (LMS): define a Message Channel metadata component, then publish()/subscribe() to it from any component regardless of where it sits in the DOM tree.

7 Lightning Data Service

Lightning Data Service (LDS) lets you read and write records directly from LWC without writing any Apex at all — useful for simple CRUD against standard or custom objects, and it comes with automatic caching, field-level security enforcement, and cross-component cache sharing built in.

8 Common LWC Mistakes

These mistakes account for the majority of LWC bugs and App Builder confusion reported by developers new to the framework.