SfSkills Domains Docs GitHub

Home / lwc / lwc-show-toast-patterns

lwc-show-toast-patterns

ShowToastEvent in LWC: variants (success/warning/error/info), modes (dismissible/pester/sticky), message formatting, NOT supported in LWR Experience Cloud sites, alternatives (lightning-alert, inline banners). NOT for custom notification types (use admin/custom-notification-types). NOT for SLDS popovers.

Open the skill folder on GitHub

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

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

VariantWhen to use
successConfirmation of successful action
warningNon-blocking caution
errorFailure requiring attention
infoNeutral status

Modes

ModeBehavior
dismissible (default)Auto-dismisses after 5 seconds; user can close
pesterStays until user dismisses (only valid for error variant)
stickyStays until user dismisses
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:

Common Patterns

Pattern: Error toast with sticky mode

this.dispatchEvent(new ShowToastEvent({
    title: 'Save failed',
    message: error.body.message,
    variant: 'error',
    mode: 'sticky'
}));
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

ContextFeedback mechanism
Lightning ExperienceShowToastEvent
Mobile Salesforce appShowToastEvent
Aura Experience Cloud siteShowToastEvent
LWR Experience Cloud siteCustom banner, lightning-alert, or inline component
Blocking confirmation neededlightning-confirm (not a toast)
Rich content / interactiveLightningModal (not a toast)
  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

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

ArtifactDescription
Toast dispatch helperUtility wrapping ShowToastEvent with defaults
LWR fallback componentBanner for Experience Cloud LWR
Accessibility snippetShort message + role='alert' pattern

Package files