Navigation And Routing

Use this skill when page changes are part of the component contract and those page changes need to survive container differences. Navigation in LWC is reliable only when it is expressed as a PageReference contract instead of as hardcoded Salesforce URLs.

Before Starting

Gather this context before working on anything in this domain:

• Is the component navigating to a Salesforce resource, an Experience Cloud page, or an external URL?
• Does the user need a real deep link that can be bookmarked or shared, or is the navigation purely in-session?
• Which containers must support the behavior, and does the chosen page-reference type exist in all of them?

Core Concepts

PageReference is the platform contract for navigation. It separates intent from concrete URL shape so Salesforce can translate the same request for Lightning Experience, mobile, and supported site containers. The moment a component falls back to /lightning/... or /s/... string building, it starts owning routing details the framework already knows better.

Use NavigationMixin Instead Of Hardcoded URLs

NavigationMixin.Navigate is for moving the user. NavigationMixin.GenerateUrl is for building stable href values when the component needs a clickable anchor, copyable link, or preview. Both work from a PageReference object rather than a guessed URL.

Page Type And Attributes Matter

standard__recordPage, standard__objectPage, standard__webPage, standard__component, and Experience Cloud page types all have different required attributes and support boundaries. Many bugs are not "navigation is broken"; they are "the wrong page-reference type was chosen for the container."

URL State Is Part Of The Contract

When a component needs deep-linkable filters or modes, the state belongs in the PageReference. Custom state keys must be namespaced, such as c__view or c__filter. If the component reads URL state, it should do so through CurrentPageReference instead of parsing browser globals directly.

Experience Cloud Requires Container Awareness

Some PageReference types differ by site technology and supported target. A navigation pattern that works in Lightning Experience can still fail in an Aura or LWR site if the destination type is not supported there. Site-safe navigation must be chosen deliberately rather than inherited from internal-app assumptions.

Common Patterns

Record-Oriented Navigation

When to use: After save, select, or row action, the component needs to open a record or object list page.

How it works: Build a record or object PageReference with explicit recordId, objectApiName, and actionName, then call Navigate.

Why not the alternative: Hardcoded Lightning URLs couple the component to one runtime and are easy to break.

Generated Links For Stable Hrefs

When to use: The component needs an anchor tag, copy link action, or a preview URL before navigation happens.

How it works: Call GenerateUrl from the same PageReference the component would use for navigation and bind the result into the UI.

Why not the alternative: Duplicating one shape for href and another for Navigate usually causes drift.

Deep-Linkable State With CurrentPageReference

When to use: The component needs URL-driven filters, tabs, or modes that should survive refresh and sharing.

How it works: Write state through the PageReference, read it through CurrentPageReference, and keep custom keys namespaced.

Why not the alternative: Parsing raw URL strings makes the component brittle and less portable across containers.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

• Navigation uses a PageReference instead of a hardcoded internal URL.
• The chosen page type is valid for the target container and user experience.
• Required attributes such as recordId or actionName are explicit.
• Custom URL state keys are namespaced.
• CurrentPageReference is used for reading URL state instead of manual parsing.
• GenerateUrl is used when the UI needs a durable href rather than immediate navigation.

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Hardcoded internal URLs are container assumptions - they often work until the component is reused in mobile or Experience Cloud.
2. Custom state keys need a namespace prefix - unnamespaced keys do not form a stable custom URL-state contract.
3. PageReference support varies by destination and container - choosing the right page type matters as much as using NavigationMixin at all.
4. Navigation and generated URLs should come from the same contract - separate implementations drift quickly and confuse users.

Output Artifacts

Related Skills

• lwc/component-communication - use when an event or LMS message is the real issue and navigation is only downstream behavior.
• lwc/lifecycle-hooks - use when navigation setup or cleanup is happening at the wrong lifecycle boundary.
• lwc/lwc-offline-and-mobile - use when mobile container behavior changes the expectations for navigation and user flow.