| name | lwc-lightning-modal |
| description | LightningModal base class (Winter '23+): extending LightningModal, open() static method, modal headers/bodies/footers, close() with result, size variants, accessibility. NOT for lightning-dialog legacy patterns (deprecated). NOT for in-page overlays (use SLDS popover). |
| category | lwc |
| salesforce-version | Spring '25+ |
| well-architected-pillars | ["User Experience","Operational Excellence"] |
| tags | ["lwc","lightning-modal","modal","dialog","accessibility"] |
| triggers | ["lightningmodal extend open method lwc","how to return result from lightning modal lwc","lightning modal size small medium large full","lightning modal close with value parent","lightning modal header body footer slots","lwc modal accessibility focus trap"] |
| inputs | ["Modal use case (confirmation, form, wizard)","Required inputs/outputs of the modal","Size and surface (desktop, mobile)"] |
| outputs | ["LightningModal subclass LWC","Parent invocation pattern with result handling","Accessibility checklist"] |
| dependencies | [] |
| version | 1.1.0 |
| author | Pranav Nagrecha |
| updated | "2026-05-19T00:00:00.000Z" |
LWC Lightning Modal
Activate when building a modal dialog in LWC — confirmation prompts, inline forms, multi-step wizards. LightningModal (GA Winter '23) replaces the earlier ad-hoc modal patterns and handles focus trap, accessibility, and lifecycle consistently.
Before Starting
- Extend
LightningModal from lightning/modal — not LightningElement.
- Modal components are opened via the static
open() method, not rendered in the parent template.
- Close via
this.close(result) — the returned promise resolves with result.
Core Concepts
Defining a modal component
import LightningModal from 'lightning/modal';
export default class MyConfirm extends LightningModal {
@api label;
handleOk() { this.close('ok'); }
handleCancel() { this.close('cancel'); }
}
Template uses <lightning-modal-header>, <lightning-modal-body>, <lightning-modal-footer>.
Opening the modal
import MyConfirm from 'c/myConfirm';
async handleOpen() {
const result = await MyConfirm.open({
label: 'Confirm Delete',
size: 'small',
description: 'Confirm deletion'
});
if (result === 'ok') { ... }
}
open() returns a Promise that resolves when this.close(value) is called.
Sizes
small, medium, large, full — set via the size option.
Accessibility
Header slot becomes the accessible label automatically. Focus trapping is built-in. First focusable element gets focus on open.
Passing data in / out
- In:
@api-decorated properties set via the open() options object.
- Out:
this.close(value) resolves the promise with value.
Common Patterns
Pattern: Confirmation dialog
const ok = await ConfirmModal.open({ label: 'Delete record?' });
if (ok === 'confirm') { /* delete */ }
Pattern: Inline form modal
Modal hosts a lightning-record-edit-form; on save, call this.close(recordId). Parent refreshes its data.
Pattern: Multi-step wizard
Maintain step state inside the modal class; each step is a different rendered fragment. Final step calls this.close(allCollectedData).
Decision Guidance
| Need | Mechanism |
|---|
| Confirmation or prompt | LightningModal |
| Inline-embedded panel | Regular LWC with SLDS panel classes |
| Full-screen takeover | LightningModal size='full' |
| Non-modal popover | SLDS popover utility CSS |
| Legacy dialog code | Migrate to LightningModal |
Recommended Workflow
- Create the modal component extending
LightningModal.
- Define
@api inputs for data passed in.
- Template uses modal header / body / footer slots.
- Implement close paths with meaningful result values.
- Parent calls
await MyModal.open(options) and handles result.
- Test keyboard navigation (Tab trap, Esc closes).
- Test screen reader announces modal label.
Review Checklist
Salesforce-Specific Gotchas
- Modal component must not render in parent template. Use
open() only.
- Dismissing via Esc or outside-click resolves with
undefined. Handle undefined as "cancelled."
- API not available before Winter '23. Older orgs need alternative patterns.
Output Artifacts
| Artifact | Description |
|---|
| Modal LWC | Subclass extending LightningModal |
| Parent invocation helper | await MyModal.open(...) wrapper |
| A11y test checklist | Keyboard + screen-reader verification |
Related Skills
lwc/lwc-accessibility-patterns — a11y fundamentals
lwc/lwc-forms-patterns — form-in-modal patterns
lwc/lwc-wizard-patterns — multi-step UX