Lwc Dynamic Components

LWC Dynamic Components

Use this skill when a Lightning Web Component must select and render a different child component at runtime — not at build time — based on record type, user role, server-side configuration, or a feature flag that cannot be resolved statically. The lwc:component directive combined with dynamic import() is the platform-supported mechanism for this pattern since Spring '23.

Before Starting

Gather this context before working on anything in this domain:

• Is the component deployed in a managed package or an unlocked package? Dynamic imports require managed-package context; unlocked packages do not support the lwc:component dynamic loading pattern.
• Is Lightning Web Security (LWS) enabled? Dynamic imports are not available in the legacy Locker Service environment. LWS is required.
• What is the complete set of components that may be rendered? Dynamic imports use static string paths resolved at bundle time — you cannot construct the module specifier from a variable at runtime.
• Does the selected component receive @api properties, and which ones? Property passing is straightforward but must be handled after the constructor is set.
• Is there an error path if the module load fails? A missing try/catch leaves the user with a blank area and no feedback.

Core Concepts

The lwc:component Directive and lwc:is

The lwc:component tag is a special host element introduced in Spring '23 that renders whatever constructor is assigned to its lwc:is property. The template syntax is:

<lwc:component lwc:is={dynamicCtor}></lwc:component>

lwc:is must receive a component constructor (a class reference), not a string name. Passing a string does nothing and renders no component. When lwc:is is null or undefined, nothing is rendered, which is the correct initial state before the import resolves.

Dynamic Import and the default Export

The import() function loads a module asynchronously and returns a Promise that resolves to the module object. LWC component modules export their class as the default export, so you must destructure default to get the constructor:

// Correct
const { default: Ctor } = await import('c/myComponent');
this.dynamicCtor = Ctor;

// Also correct (explicit)
const module = await import('c/myComponent');
this.dynamicCtor = module.default;

// Wrong — this sets lwc:is to the module object, not the constructor
this.dynamicCtor = await import('c/myComponent');

Assign the constructor to a reactive property decorated with @track or declared as a class field so the template re-evaluates when it changes.

Lazy Loading and Bundle Splitting

Dynamic imports cause the module to be loaded as a separate chunk at runtime rather than included in the page's initial JavaScript bundle. This is the main performance benefit: a large component that is only sometimes needed does not inflate the first-paint payload. The component is fetched the first time import() is called; subsequent imports of the same module resolve from cache.

This also means there is a network round-trip the first time the component loads. For components that are almost always needed, a static import is cheaper. Reserve dynamic import for components that are genuinely conditional and large enough to justify the separate fetch.

Property Passing and Event Handling

After setting lwc:is, you can pass @api properties to the dynamic component using standard attribute binding on the lwc:component tag. The dynamic child can dispatch custom events; the parent listens with a standard oneventname handler on the lwc:component element. There is no difference from static composition once the constructor is resolved.

Common Patterns

Mode 1: Implement a Dynamic Component Renderer

When to use: You need to select from a known set of LWC components at runtime based on record type, user role, or server-returned configuration.

How it works:

1. Declare a reactive property for the constructor and an optional map for @api inputs:

import { LightningElement, api, track } from 'lwc';

export default class DynamicFormRouter extends LightningElement {
    @api recordTypeId;
    @track dynamicCtor = null;
    @track componentProps = {};

    async connectedCallback() {
        await this._loadComponent();
    }

    async _loadComponent() {
        try {
            let mod;
            if (this.recordTypeId === '012ABC') {
                mod = await import('c/caseDetailView');
            } else if (this.recordTypeId === '012DEF') {
                mod = await import('c/orderDetailView');
            } else {
                mod = await import('c/genericDetailView');
            }
            this.dynamicCtor = mod.default;
            this.componentProps = { recordId: this.recordTypeId };
        } catch (err) {
            console.error('Failed to load dynamic component', err);
            this.dynamicCtor = null;
        }
    }
}

2. In the template, render the dynamic component and bind properties:

<template>
    <template lwc:if={dynamicCtor}>
        <lwc:component lwc:is={dynamicCtor}
                       record-id={componentProps.recordId}
                      
        </lwc:component>
    </template>
    <template lwc:else>
        <lightning-spinner alternative-text="Loading..."></lightning-spinner>
    </template>
</template>

Why not the alternative: Using a chain of lwc:if blocks with statically imported components works for a small fixed set, but it instantiates all imported modules in the bundle even when only one renders. Dynamic import defers the unused ones entirely.

Mode 2: Review an Existing Dynamic Component Implementation

Check for:

• Is lwc:is receiving module.default, not the raw module object?
• Is the import call inside a try/catch? What does the UI show when the import fails?
• Is the reactive property triggering a re-render? Ensure it is a tracked or reactive field.
• Is the package type managed? If this is in an unlocked package, the pattern will not work.
• Is LWS enabled? Check Setup > Session Settings > Use Lightning Web Security.
• Are @api properties correctly bound on the lwc:component element?
• Does the import specifier use a literal string, not a computed value?

Mode 3: Troubleshoot a Broken Dynamic Component

Common failure modes and their root cause:

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:

• lwc:is is assigned module.default, not the raw module object.
• The import specifier is a literal string, not a computed or template-literal value.
• The dynamic import is wrapped in try/catch with a visible error state for the user.
• The reactive property holding the constructor is properly declared (@track or class field) so the template re-evaluates.
• The component runs in a managed package if dynamic imports are in use (unlocked packages are not supported).
• Lightning Web Security is enabled in the org.
• @api properties are bound directly on the <lwc:component> element.
• A loading state (spinner or skeleton) is shown while the import resolves.
• Child component events are handled via oneventname on the <lwc:component> element.

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. module.default omission silently renders nothing — Assigning the Promise result of await import('c/foo') directly to lwc:is passes a module namespace object, not a constructor. The component silently renders nothing with no console error in most orgs. Always destructure default.
2. Unlocked packages do not support dynamic import — The lwc:component dynamic loading pattern is supported only in managed packages. Teams building in unlocked packages who encounter this will see a runtime failure. There is no workaround short of switching package type.
3. The import specifier must be a static string — The LWC build toolchain analyzes import calls at compile time to build the module chunk graph. A computed specifier like `c/${componentName}` will cause a build error or be silently ignored. All candidate components must appear as literal import strings in the source.
4. Dynamic imports are not prefetched — Unlike static imports that are included in the page bundle, dynamic imports fetch their chunk on the first call. This introduces a round-trip latency the first time the user triggers the load. Show a loading indicator and consider whether the round-trip cost is acceptable.
5. LWS must be enabled — Legacy Locker Service does not support import(). If an org has not migrated to Lightning Web Security, dynamic components will fail with a runtime error. Check Setup > Session Settings.

Output Artifacts

Related Skills

• lwc/lwc-performance — use when the goal is general bundle optimization and the dynamic component pattern is one of several options being weighed.
• lwc/lwc-conditional-rendering — use when the component set is known at build time and lwc:if chains are the right tool.
• lwc/lwc-in-flow-screens — use when the dynamic component needs to run inside a Flow screen component context.