Home / lwc / lwc-base-component-recipes

lwc-base-component-recipes

Use this skill when building record forms or data tables with Salesforce standard base components: lightning-record-form, lightning-record-edit-form, lightning-record-view-form, and lightning-datatable.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Performance
• Reliability
• Security

• lwc
• base-components
• lightning-record-form
• lightning-datatable
• forms
• data-display
• lightning-card
• lightning-combobox
• lightning-layout

Open the skill folder on GitHub

LWC Base Component Recipes

This skill activates when a practitioner needs to build record forms or data tables using Salesforce standard base Lightning components. It covers component selection, required attribute configuration, layout control, inline editing, row actions, and the trade-offs between declarative and custom approaches.

Attribute contracts live in the Component Library, not here and not in the LWC Developer Guide. The Lightning Web Components Developer Guide documents which base components exist, how they compose, how they are styled, and how they behave in containers. It does not publish the per-component attribute, event, and method tables — those are on the Specification and Documentation tabs of each component in the Component Reference (0 L4727; 1 L4804, L4812). Every attribute named in this package that the guide itself does not print carries an UNVERIFIED (2026-09-05) marker beside it. Confirm those against the Component Library before shipping, and never copy an attribute name out of a generated snippet without checking it.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the object API name and which field API names (not labels) are needed. Field API names drive both fields attributes and lightning-input-field / lightning-output-field children.
• Determine whether the form needs a fully custom layout (field order, sections, custom buttons, field-level messages) or whether a standard layout is acceptable. This is the primary driver for choosing lightning-record-form vs lightning-record-edit-form.
• For lightning-datatable, establish whether inline editing, row actions, or sorting is required before scaffolding — these each add distinct wiring.
• The most common wrong assumption is that lightning-record-form supports arbitrary field ordering. lightning-record-form has no "Custom Layout for Fields" capability at all — that column belongs to lightning-record-view-form and lightning-record-edit-form (lwc_guide data-get-user-input L5426, L5431).
• Platform constraints: lightning-record-form, lightning-record-edit-form, and lightning-record-view-form work with Salesforce record data only, are limited to the objects User Interface API supports, and go through Lightning Data Service (lwc_guide base-components-containers L4710; data-get-user-input L5414, L5418). lightning-datatable and lightning-tree-grid are not supported on mobile devices (lwc_guide data-table-vs-tree-grid L5600), and datatable performance is best at a maximum of 1,000 rows and 5 columns (lwc_guide data-table-performance L6311).
• Establish which containers the component must run in. Base components run in Lightning Experience, Experience Builder sites, and the Salesforce mobile app, but only a subset support server-side rendering on LWR sites, and lightning/platformShowToastEvent is not supported in LWR sites at all — use lightning/toast (lwc_guide base-components-containers L4714; base-components-all L4649, L4651; base-components-patterns L4773).

Questions to Ask Before Configuring

Ask these before the first <lightning-*> tag is typed. Each one traces to a failure documented in references/gotchas.md that the component will not raise at compile time.

What a proper base-component composition adds over just doing it: the UI inherits SLDS updates, keyboard behaviour, ARIA state management and WCAG 2.1 AA contrast from Salesforce rather than from your own markup (lwc_guide base-components-accessibility L4953–4957), the form path enforces CRUD and FLS through Lightning Data Service instead of a bespoke Apex surface, and every attribute you did use is one the Component Library will keep supporting.

Core Concepts

The base-component-first decision

Four options, in the order you should try them (lwc_guide create-components-css-slds-blueprint L1733–1737, create-components-accessibility L3977, create-use-third-party-components L4188):

The load-bearing sentence is lwc_guide L1737: "If SLDS updates the related blueprint, your component code isn't updated automatically … Salesforce automatically updates the base components when SLDS updates the associated blueprint." That is the whole argument for base-first, and it is also the argument against replacing an SLDS class with your own (L1894–1895) or styling from rendered output (L1890–1891).

The catalogue, by family

Base components live in the lightning namespace, use the lightning-component-name form in markup and the lightning/moduleName form for JavaScript imports, and are grouped into these categories (lwc_guide base-components-all L4546–4690, base-components-considerations L4724–4725):

Most base components were first available in Spring '19 (API 45.0), and base components are not versioned — lowering your bundle's apiVersion does not roll a base component back to older behaviour, and anything below 58.0 is treated as 58.0 (lwc_guide base-components-all L4545, base-components-min-version L4697, L4701).

Composition versus flat structure

Two shapes, and picking the wrong one is the single most common markup failure in this domain (lwc_guide base-components-compose L4850–4887):

• Composition (slots). The parent exposes slots and you nest children: lightning-accordion / -section, lightning-button-group / lightning-button, lightning-button-menu / lightning-menu-item, lightning-layout / -item, lightning-tabset / lightning-tab, lightning-record-edit-form / lightning-input-field, lightning-record-view-form / lightning-output-field, lightning-progress-indicator / lightning-progress-step (L4857–4866). Slots are the recommended default (L4914, L4925).
• Flat structure (a configuration attribute). The parent renders children internally from an array you pass: lightning-combobox, lightning-select, lightning-checkbox-group, lightning-radio-group, lightning-dual-listbox (options), lightning-datatable (columns + data), lightning-tree (items), lightning-pill-container (items), lightning-map (map-markers) (L4873–4882). Use it when you would otherwise render large numbers of composed elements (L4886).

lightning-card is the one you will use most: it has a default slot and three named slots (L4909). In LWC — unlike Aura — title and footer are text-only attributes, and card actions go in a named actions slot rather than an actions attribute (L11674).

Feeding a combobox from picklist metadata

lightning-combobox "displays a dropdown list (picklist) of selectable options" and takes label / value pairs on its options attribute (lwc_guide data-wire-base-components L6588–6589, base-components-compose L4875). The metadata chain is fixed (lwc_guide reference-wire-adapters-picklist-values L14949, L14958–14964):

1. @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT }) → read data.defaultRecordTypeId.
2. Hold that in a reactive property and pass it to @wire(getPicklistValues, { recordTypeId: '$recordTypeId', fieldApiName: RATING_FIELD }). Both parameters are required; objectApiName is not accepted on this adapter.
3. Map data.values to { label, value }. Use value for anything written back to Salesforce — label is translated into the running user's language through Translation Workbench, value is always the untranslated API name.
4. If there is no default record type, the master record type is 012000000000000AAA (L14949).

For all picklists of a record type at once, use getPicklistValuesByRecordType instead (L14959).

Read-only summaries with lightning-record-view-form

lightning-output-field must be a direct child of lightning-record-view-form; it must not be nested in another element such as lightning-layout (lwc_guide migrate-map-aura-lwc-components L11727). Put the form inside a lightning-layout-item and keep the output fields directly under the form. The form family adapts to the org's display density by default or with density="auto", and can be overridden with density="compact" or density="comfy" — cozy is not a supported value (L6329–6331). lightning-output-field supports two variants, standard (default) and label-hidden, and a hidden label is still available to assistive technology (L6346–6347).

Testing base-component composites

The sfdx-lwc-jest lightning-stubs match the real components' API but implement none of the behaviour. Three consequences drive every test in references/code-examples.md (lwc_guide unit-testing-using-jest-patterns L12622, L12625–12627):

• No events fire from a stub — but you can call dispatchEvent() against one. That is how you simulate a combobox change or a menu select.
• Not every property is reflected as a DOM attribute. Read the property off the queried stub (el.options, el.value), never el.getAttribute('options').
• Do not depend on slot render order. If the expected content is present, the test should pass regardless of which named slot rendered first.

Common Patterns

Pattern: the everyday composite — card + layout + combobox + menu + spinner + read-only summary

When to use: Almost every "panel on a record page" request. It is one card, one responsive grid, one metadata-driven picklist, one action menu, one loading state, and one read-only field summary.

The complete bundle — .html, .js, .js-meta.xml, package.xml, the Jest suite, the deploy order and the verification steps — is in references/code-examples.md. The structural rules it encodes:

<!-- shape only; the full bundle is in references/code-examples.md -->
<lightning-card title="Account Summary" icon-name="standard:account">
  <lightning-button-menu slot="actions" alternative-text="Panel actions" onselect={handleMenuSelect}>
    <lightning-menu-item value="refresh" label="Refresh"></lightning-menu-item>
  </lightning-button-menu>

  <div class="slds-var-p-horizontal_medium">
    <template lwc:if={isLoading}>
      <lightning-spinner alternative-text="Loading" size="small"></lightning-spinner>
    </template>

    <lightning-layout multiple-rows="true">
      <lightning-layout-item size="12" small-device-size="6" padding="around-small">
        <lightning-combobox label="Rating" value={rating} options={ratingOptions}
                            onchange={handleRatingChange}></lightning-combobox>
      </lightning-layout-item>
      <lightning-layout-item size="12" small-device-size="6" padding="around-small">
        <!-- the FORM goes in the layout item; the OUTPUT FIELDS stay directly under the form -->
        <lightning-record-view-form record-id={recordId} object-api-name="Account">
          <lightning-output-field field-name="Industry"></lightning-output-field>
          <lightning-output-field field-name="AnnualRevenue"></lightning-output-field>
        </lightning-record-view-form>
      </lightning-layout-item>
    </lightning-layout>
  </div>
</lightning-card>

size and small-device-size on lightning-layout-item are printed by the guide: small-device-size="9" gives 75% width at the 480px-and-above breakpoint while size="12" takes the full width on mobile (lwc_guide create-components-css-slds-blueprint L1768). slot="actions" on the menu follows L11674. multiple-rows, padding, alternative-text and size on lightning-spinner, icon-name on lightning-card, and onselect on lightning-button-menu are UNVERIFIED (2026-09-05): the LWC Developer Guide never prints these attribute names; the guide only records that lightning-button-menu does not support onclick or onclose (L11672) and that lightning-icon/lightning-avatar expose alternative-text (L4964). Confirm each on the Component Library Specification tab.

Pattern: Custom Save Button with Field-Level Error Display

When to use: The form needs a non-standard button placement, a confirmation step before save, or field-level validation messages shown below specific fields.

Depth on lightning-record-edit-form validation, reportValidity(), and file upload lives in lwc/lwc-forms-and-validation; the create/edit/view selection matrix lives in lwc/lwc-lightning-record-forms. Use the pattern below only for the composition question — where the buttons and messages go inside the form.

How it works:

<!-- myForm.html -->
<template>
  <lightning-record-edit-form
    record-id={recordId}
    object-api-name="Contact"
    onsubmit={handleSubmit}
    onsuccess={handleSuccess}
    onerror={handleError}
  >
    <lightning-messages></lightning-messages>
    <lightning-input-field field-name="FirstName"></lightning-input-field>
    <lightning-input-field field-name="LastName"></lightning-input-field>
    <lightning-input-field field-name="Email"></lightning-input-field>
    <lightning-button type="submit" label="Save Contact" variant="brand"></lightning-button>
    <lightning-button label="Cancel" onclick={handleCancel}></lightning-button>
  </lightning-record-edit-form>
</template>

// myForm.js
import { LightningElement, api } from 'lwc';
export default class MyForm extends LightningElement {
  @api recordId;

  handleSubmit(event) {
    event.preventDefault();
    const fields = event.detail.fields;
    // Custom pre-save logic here, then:
    this.template.querySelector('lightning-record-edit-form').submit(fields);
  }

  handleSuccess(event) {
    const updatedRecord = event.detail.id;
    // fire toast or navigate
  }

  handleCancel() {
    // navigate away or reset
  }
}

lightning-record-edit-form fires four custom events — error, load, submit, success — and does not provide its own Save and Cancel buttons the way lightning-record-form does, so you add lightning-button children and include lightning-messages for automatic error display (lwc_guide data-edit-record L5489–5490, L5500–5504). The record Id is not available on the submit event; read it from success (lwc_guide data-considerations L6376). event.preventDefault() on onsubmit followed by a manual submit(fields) call is UNVERIFIED (2026-09-05): the guide names the submit event but never documents the submit(fields) method or the preventDefault-then-resubmit sequence — that contract is in the Component Library.

Why not lightning-record-form: lightning-record-form combines the view and edit forms and manages its own buttons; the "Custom Layout for Fields" and "Custom Rendering of Record Data" capabilities belong to lightning-record-view-form and lightning-record-edit-form (L5424–5431).

Pattern: lightning-datatable with Inline Editing

When to use: A table of records needs in-place cell editing without navigating to a record page.

lwc/lwc-data-table owns first-time datatable setup and lwc/lwc-datatable-advanced owns inline edit, custom cell types and infinite scroll. Kept here only as the contract summary, because choosing datatable at all is a base-component decision — and one with a hard container constraint.

<!-- dataTable.html -->
<template>
  <lightning-datatable
    key-field="Id"
    data={tableData}
    columns={columns}
    draft-values={draftValues}
    onsave={handleSave}
  ></lightning-datatable>
</template>

// dataTable.js
import { LightningElement, wire } from 'lwc';
import { updateRecord } from 'lightning/uiRecordApi';
import { refreshApex } from '@salesforce/apex';

export default class DataTable extends LightningElement {
  tableData = [];
  draftValues = [];

  columns = [
    { label: 'Name', fieldName: 'Name', type: 'text' },
    { label: 'Phone', fieldName: 'Phone', type: 'phone', editable: true },
  ];

  async handleSave(event) {
    const updates = event.detail.draftValues;
    const updatePromises = updates.map(row =>
      updateRecord({ fields: { Id: row.Id, ...row } })
    );
    try {
      await Promise.all(updatePromises);
      this.draftValues = []; // clear draft values on success
    } catch (e) {
      // surface error via showToast
    }
  }
}

The contract facts, all printed by the guide: key-field is required and associates each row with a record; columns takes label, fieldName and type, and data takes the rows; editable: true on a column enables inline edit; edits land in draft-values; event.detail.draftValues carries the edited values and the record Id; and clearing draftValues is what hides the Save/Cancel footer (lwc_guide data-table-inline-edit L5675, L5678, L5711–5712; base-components-compose L4877). Neither datatable nor tree-grid is supported on mobile devices (L5600).

Why not manual table markup: rebuilding the table means rebuilding the two-mode keyboard model — navigation mode with tabindex="-1" on actionable elements, action mode with tabindex="0", and arrow-key movement between cells — that datatable implements for you (lwc_guide data-table-a11y L6215–6233).

Contract Mistakes That Compile Fine

These produce a component that renders, deploys, and silently does the wrong thing.

Decision Guidance

Recommended Workflow

1. Inventory the screen against the catalogue. Write down every visual element the request implies, then map each to a family in the catalogue table above. Anything you cannot map is a blueprint or third-party decision — resolve it with the Decision Guidance table before writing markup.
2. Answer the Questions table. The container question sets <supportedFormFactors> and the toast module; the picklist and record-type questions decide whether you need the getObjectInfo → getPicklistValues chain.
3. Pick composition or flat structure per component. Slots for card, layout, button-group, button-menu, accordion, tabset and the record forms; an options / columns / items array for combobox, select, checkbox-group, radio-group, datatable, tree.
4. Build from references/code-examples.md. Copy the accountSummaryPanel bundle — it already encodes the layout-item nesting, the output-field-must-be-a-direct-child rule, the wire chain, the spinner state and the .js-meta.xml. Use templates/lwc/component-skeleton/ for a component this recipe does not cover, and templates/lwc/jest.config.js for the harness.
5. Verify every attribute you typed against the Component Library. The guide does not publish attribute tables. Anything not printed in this package with a line cite is an assumption — mark it or check it. lwc:ref instead of id; onchange not oninput; a label on every input.
6. Write the Jest suite against the stubs, not against the DOM. Query the lightning-* stub, read properties off it, and dispatchEvent() at it. Assertions on getAttribute() of a stub pass or fail for reasons unrelated to your component — see references/gotchas.md.
7. Run the checker, then deploy. python3 skills/lwc/lwc-base-component-recipes/scripts/check_lwc_base_component_recipes.py --manifest-dir force-app/main/default/lwc — zero ERRORs before review, --strict in CI so the WARNs (raw SLDS button markup, datatable on a mobile form factor, getAttribute on a stub, platformShowToastEvent in an LWR bundle) also block. Deploy order and the Setup verification steps are at the end of references/code-examples.md.

Review Checklist

Run through these before marking work in this area complete:

• [ ] Every lightning-* attribute used was confirmed on the Component Library Specification tab, not inferred from a snippet
• [ ] object-api-name uses the API name, not the label (e.g., Account not Accounts, Custom_Object__c not Custom Object)
• [ ] record-id is bound via @api recordId and passed in from the parent or page; not hardcoded
• [ ] key-field on lightning-datatable is set to a field that is unique across all rows (almost always Id)
• [ ] draft-values is reset to [] after a successful inline edit save to dismiss the save/cancel bar
• [ ] Field-level security: tested with a user who lacks access to one of the listed fields to confirm graceful omission
• [ ] onsuccess handler fires a toast or navigates; form is not left in a stale submitted state
• [ ] lightning-messages is present inside lightning-record-edit-form when using a custom submit button, so server errors surface
• [ ] Every lightning-input, lightning-combobox, lightning-select, lightning-radio-group and lightning-checkbox-group has a label
• [ ] Every lightning-output-field is a direct child of its lightning-record-view-form, not nested in lightning-layout
• [ ] Nothing but lightning-layout-item (plus plain HTML and text) sits directly inside lightning-layout
• [ ] No .slds-* selector is overridden and no CSS targets a base component's rendered internals
• [ ] .js-meta.xml declares <supportedFormFactors>, and Small is absent from any bundle containing lightning-datatable or lightning-tree-grid
• [ ] Elements are located with lwc:ref / data-*, never a rendered id
• [ ] Jest assertions read properties off the base-component stub and dispatch events at it; no getAttribute on a lightning-* element

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems. Full write-ups, each with What happens / When it occurs / How to avoid, are in references/gotchas.md:

1. lightning-record-form has no custom-field-layout capability at all — the fix is the edit or view form, not a different fields array.
2. Stale draft-values on a datatable leave the save bar up and replay edits on the next save.
3. Toggling lwc:if around a record-edit form destroys unsaved input.
4. FLS omits fields silently, and an admin never sees it.
5. Rebuilding columns on every render resets scroll position.
6. lightning-output-field nested in lightning-layout renders nothing.
7. getPicklistValues returns translated labels — saving the label writes the wrong string.
8. lightning-datatable and lightning-tree-grid do not work on mobile, and nothing warns you at deploy time.
9. Jest stubs fire no events and do not reflect every property as an attribute.
10. lightning/platformShowToastEvent is silent on LWR sites.
11. lightning-accordion-section's title attribute is reserved for internal use in LWC.

Output Artifacts

Reference Files

Related Skills

• lwc/lwc-lightning-record-forms — owns the record-form vs record-edit-form vs uiRecordApi selection matrix in depth.
• lwc/lwc-forms-and-validation — owns reportValidity(), client-side validation, and file upload flows.
• lwc/lwc-data-table — owns first-time datatable setup: columns, key-field, sorting, row actions.
• lwc/lwc-datatable-advanced — owns inline edit, custom cell types, infinite scroll, row errors.
• lwc/lwc-modal-and-overlay — owns LightningModal, the one other base component you may extend.
• lwc/lwc-toast-and-notifications — owns ShowToastEvent, lightning/toast, and notification types.
• lwc/lwc-navigation-mixin — owns NavigationMixin for row actions and menu items that navigate.
• lwc/lwc-testing — owns the Jest harness; this skill only adds what the base-component stubs change.
• lwc/lwc-css-and-styling — owns scoped CSS and the shadow boundary; read it before styling a base component.
• lwc/lwc-styling-hooks — owns --slds-c-* / --slds-g-* theming and the SLDS 2 transition.
• lwc/wire-service-patterns — owns @wire mechanics behind the getObjectInfo → getPicklistValues chain.
• lwc/lwc-accessibility — owns the full a11y review; this skill only covers what base components give you for free.

Package files

• references/code-examples.md
• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/lwc-base-component-recipes-template.md
• scripts/check_lwc_base_component_recipes.py