Lwc Show Toast Patterns

LWC ShowToast Patterns

Activate when surfacing user feedback in LWC. ShowToastEvent (from lightning/platformShowToastEvent) is the idiomatic toast API in Lightning Experience and Experience Cloud Aura sites — but NOT supported in LWR (Lightning Web Runtime) sites. Pick the right tool per context.

Before Starting

• Determine runtime. Lightning Experience / mobile Salesforce app / Aura Experience Cloud → ShowToastEvent works. LWR → NOT supported, use alternatives.
• Pick the variant. success / warning / error / info — each has distinct styling.
• Pick the mode. dismissible (default, 3s auto), pester (stays until dismissed, errors only), sticky (stays until dismissed).

Core Concepts

Basic dispatch

import { LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class MyCmp extends LightningElement {
    notify() {
        this.dispatchEvent(new ShowToastEvent({
            title: 'Saved',
            message: 'Record updated successfully',
            variant: 'success',
            mode: 'dismissible'
        }));
    }
}

Variants

Modes

Message placeholders and links

this.dispatchEvent(new ShowToastEvent({
    title: 'Record Saved',
    message: 'See {0}',
    messageData: [
        { url: '/lightning/r/Account/0012x.../view', label: 'Acme' }
    ],
    variant: 'success'
}));

{0} is replaced by the object at index 0 — either plain text or {url, label} for a link.

LWR Experience Cloud caveat

ShowToastEvent is silently ignored on LWR sites. Alternatives:

• lightning-alert / lightning-confirm modals
• Inline banner component using lightning-icon + SLDS notification classes
• Custom toast implementation with lightning-layout + CSS animation

Common Patterns

Pattern: Error toast with sticky mode

this.dispatchEvent(new ShowToastEvent({
    title: 'Save failed',
    message: error.body.message,
    variant: 'error',
    mode: 'sticky'
}));

Pattern: Link-in-message toast

this.dispatchEvent(new ShowToastEvent({
    title: 'Record Created',
    message: 'View {0}',
    messageData: [
        { url: `/lightning/r/Account/${recordId}/view`, label: accountName }
    ],
    variant: 'success'
}));

Pattern: LWR-compatible fallback

// lwrToast.js — a custom banner component
@api message;
@api variant;
isShown = false;
show() { this.isShown = true; setTimeout(() => this.isShown = false, 3000); }

Decision Guidance

Recommended Workflow

1. Confirm target runtime (Lightning vs LWR) before writing.
2. Dispatch ShowToastEvent with explicit variant and mode.
3. For errors, use sticky or pester so users can read.
4. For cross-runtime components, check @salesforce/client/formFactor and fall back to a banner in LWR.
5. Test toasts in the actual runtime, not just LEX (LWR renders differently).
6. For accessibility, keep toast messages ≤75 characters so screen readers announce cleanly.
7. Document that LWR does not render toasts — downstream teams must be warned.

Review Checklist

• Target runtime verified (LWR alternatives used where needed)
• Variant matches semantic intent
• Error variants use sticky or pester (not dismissible)
• Message kept short for accessibility
• Link-in-message uses messageData placeholders
• Fallback implemented for LWR sites

Salesforce-Specific Gotchas

1. LWR Experience Cloud silently swallows ShowToastEvent — no console warning, just no toast. Use lightning-alert or a custom banner.
2. pester mode is only valid for variant='error'. With other variants it falls back to dismissible.
3. Toasts dispatched before the component is fully rendered may be lost. Use renderedCallback or defer to after async work completes.
4. Custom toast styling is not supported. slds-notify_toast classes apply to the built-in component, not reproducible outside the framework.

Output Artifacts

Related Skills

• lwc/lwc-lightning-modal — when blocking user attention is required
• lwc/lwc-accessibility-patterns — semantic feedback patterns
• admin/custom-notification-types — for async/server-side notifications