LWC Container

Overview

The LWC Container lets you place custom Lightning Web Components (LWCs), built by developers, directly on your Dynamic Component canvas. Use it to:

• Pass data to LWCs: Send values from your Dynamic Component's resources (Variables, Constants, Formulas, or attributes of other Avonni components) into the @api properties of your custom LWC.

• Add custom functionality: Bring in UI elements, business logic, or integrations that your developer built as an LWC, without modifying the LWC's code.

Choosing the Right LWC Container: Avonni Data LWC Container vs. LWC Container

Unlike the Data LWC Container component, this LWC Container does not include built-in data querying, filtering, searching, or pagination. It's simply a container for your LWC, with data handling managed either within the LWC itself or passed to it via input properties from the Dynamic Component.

If you want to use Avonni's data query and search features within your LWC, consider using the Avonni Data LWC Container component instead.

---

Adding the LWC Container Component

From the Component Library (left panel), find the "LWC Container" component and drag it onto your canvas.

---

Configuration

Select the LWC Container component on the canvas to access its properties in the Properties Panel.

Basic Properties

• API Name: (Text) A unique identifier for this LWC Container instance (e.g., MyCustomLwcHolder).

Selecting the LWC

• Enter the exact API name of the custom Lightning Web Component (typically built by your developer) you want to embed. This name should follow the format namespace/componentName (e.g., c/myCustomCardList if in the default 'c' namespace, or yourNamespace/specialDisplay if part of a specific namespace).

Passing Data to the LWC (Attributes)

Custom LWCs often expect data to work correctly, like an @api recordId or @api config. The LWC Container lets you send values from your Dynamic Component directly into those @api properties, making the LWC dynamic and context-aware.

Think of the @api properties in your LWC as input sockets, and the values from your Dynamic Component as power sources or data cables that plug in.

How to Pass Data

You define which data goes into which input of your LWC using the Attributes section in the Properties Panel.

Step-by-Step Example

Let’s say your developer gave you an LWC that expects

@api recordId;
@api configOptions;

Here’s how to feed it the right data:

1. Click "Add Input Property" in the LWC Container’s settings.

2. For each property:

   • LWC Property API Name: Enter the name of the @api input (e.g., recordId).

   • Value: Choose the data to send from your Dynamic Component. You can pick:

     • A Variable (e.g., selectedAccountId)

     • A Constant (e.g., "standard-view")

     • A Formula

     • A Component attribute (e.g., @MyDataTable.firstSelectedRow.Id)

     • A Global variable (like $Component.recordId)

Real-Life Use Case

Scenario: You’re designing a page for Account records, and you want to show a custom timeline LWC that needs the current recordId and some settings.

Here’s what you do:

Name	Value	What It Does
recordId	$Component.recordId	Sends the current record’s ID into the LWC
configOptions	{timelineConfigJson} (Variable)	Sends a custom JSON string stored in a Text Variable

Now, when the page loads, the LWC receives:

• the correct Account ID, and

• a set of config options for display.

And it works dynamically without modifying the code

Best Practices

• Name must exactly match the @api name in your LWC’s code (case-sensitive).

• Use the Mapped Value to select valid Dynamic Component resources (Variables, Constants, Formulas, component attributes, or global variables).

• Ensure the value's data type is compatible with what the LWC expects (e.g., don't send text to a boolean input).

• You can pass as many properties as needed by adding multiple items

Custom Event Integration

The LWC Container supports custom events that trigger interactions defined in the Builder, allowing two-way communication between your LWC and the visual canvas.

How It Works

In the Builder

• Select the LWC Container.

• Go to the Interactions panel.

• Add an interaction triggered by a Custom Event name (e.g., refreshTimeline, showFormModal).

• Choose the action (e.g., navigate, show modal, update records, etc.).

In Your LWC Dispatch an event using

this.dispatchEvent(new CustomEvent('myCustomEventName'));

The event name must exactly match the one configured in the Builder (case-sensitive).

What Happens Next

The LWC Container listens for the event, catches it, and executes the mapped interaction—no additional setup required.

Best Practices

• Use descriptive, unique event names to avoid conflicts.

• Always match names case-sensitively.

• Document expected events so builders can configure the right interactions.

Handling Builder and Preview Modes

The LWC Container automatically passes two boolean attributes to your embedded LWC, which you can declare as @api properties:

• isBuilder (Boolean): This attribute is true when your LWC is displayed within the Avonni Dynamic Component Builder. In this mode, your LWC is not fully interactive. Developers can use this flag to:

  • Display a simplified placeholder or design-time representation instead of rendering full, complex content.

  • Prevent unnecessary data fetching, API requests, or complex calculations not needed during design.

• isPreview (Boolean): This attribute is true when your LWC is displayed in the Avonni Dynamic Component's Preview mode (before the Dynamic Component is published or used live on a Salesforce page). Developers can use this flag to:

  • Show a simplified or sample data version of the component.

  • Avoid making unintended live API calls or database queries during preview.

Styling & Visibility (for the Container)

These settings apply to the LWC Container itself, not the internal styling of the LWC it holds (which is controlled by the LWC's own CSS).

• Margin, Padding: Standard Avonni styling options control the spacing and dimensions of the container frame.

• Set Component Visibility: Controls whether the entire LWC Container (and thus the embedded LWC) is visible. Bind to a Boolean resource for dynamic visibility.

---

Examples

Displaying Stock Information for a Selected Product

Scenario: You want to display stock information for a product selected elsewhere in the page—like from a data table, a form field, or a calculated formula. A developer provides a custom LWC called productStockViewer that accepts a productId via @api.

You’ll pass this productId dynamically using the LWC Container’s Attributes section.

LWC Configuration in Avonni Dynamic Component

In your Dynamic Component (e.g., on a Product-related page):

1. Add an LWC Container to the canvas.

2. Set these values in the Properties Panel:

   • API Name: stockViewerContainer

   • LWC Name: c/productStockViewer

3. In the Attributes section, click Add Item:

   • Name: productId

   • Value:

     • From a data table: $Component.ProductTable.selectedRow.productId,

     • Or from a variable or formula as needed.

Example Attribute Mapping Table

Name	Value	What It Does
productId	$Component.ProductTable.selectedRow.productId	Sends the selected product’s ID into the custom LWC

💡 You can also pass any other dynamic source (form field, variable, formula).

Full Code: productStockViewer LWC

This example LWC:

• Reactively receives a productId via @api,

• Simulates an async stock lookup,

• Shows dynamic stock info or loading UI.

✅ productStockViewer.html

<template>
    <lightning-card title="Stock Info" icon-name="utility:info">
        <div class="slds-p-around_medium">
            <template if:true={productId}>
                <p>Product ID: <strong>{productId}</strong></p>
                <template if:true={stock}>
                    <p>📦 Stock: <strong>{stock}</strong></p>
                </template>
                <template if:false={stock}>
                    <p>⏳ Loading stock data...</p>
                </template>
            </template>
            <template if:false={productId}>
                <p>No product selected</p>
            </template>
        </div>
    </lightning-card>
</template>

---

✅ productStockViewer.js

import { LightningElement, api } from 'lwc';

export default class ProductStockViewer extends LightningElement {
    _productId;
    stock = null;

    @api
    set productId(value) {
        this._productId = value;
        this.stock = null;
        if (value) {
            this.fetchStockData(value);
        }
    }

    get productId() {
        return this._productId;
    }

    fetchStockData(productId) {
        // Simulated async call (replace with real API if needed)
        setTimeout(() => {
            this.stock = Math.floor(Math.random() * 100);
        }, 1000);
    }
}

---

✅ productStockViewer.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>63.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

Custom LWC Using @api Inputs and Interactions

This example shows a minimal custom LWC that uses:

• @api isBuilder and @api isPreview to control design/preview behavior,

• @api value to receive dynamic content,

• A custom event (showtoast) to trigger Avonni interactions.

customLwcComponent.js

import { LightningElement, api } from 'lwc';

export default class LwcComponent extends LightningElement {
    @api isBuilder;
    @api isPreview;
    @api value;

    handleButtonClick() {
        this.dispatchEvent(new CustomEvent('showtoast'));
    }
}

customLwcComponent.html

<template>
    <div lwc:if={isBuilder} class="slds-text-align_center slds-text-title_caps slds-p-around_large">
        This is a placeholder for the builder mode.
    </div>
    <div lwc:elseif={isPreview} class="slds-text-align_center slds-text-title_caps slds-p-around_large">
        This is a placeholder for the preview mode.
    </div>
    <div lwc:else class="slds-box slds-theme_shade">
        <div class="slds-text-heading_small slds-p-bottom_small">
            LWC Custom Component
        </div>
        <p class="slds-text-title_caps">Custom Value Attribute:</p>
        <p class="slds-p-bottom_small">{value}</p>
        <lightning-button
            label="Dispatch Custom Event 'showtoast'"
            onclick={handleButtonClick}
        ></lightning-button>
    </div>
</template>

Embedding third-party and managed package components

The LWC Container can load any Lightning Web Component that is deployed to your org with isExposed: true in its .js-meta.xml, regardless of whether it comes from your own code, a managed package, or a Salesforce product like Education Cloud, Health Cloud, or Financial Services Cloud.

This means that if a third-party component is built as a standard LWC, you can embed it in the LWC Container and apply visibility rules, pass data through @api properties, and listen for custom events — the same way you would with your own custom LWCs.

What works

Component type	Works in LWC Container?	Notes
Custom LWCs built by your team	Yes	Standard use case. Pass @api properties and listen for custom events.
Managed package LWCs (Industries Cloud, ISV apps)	Yes, if the component has isExposed: true	Use the managed package namespace: industryNamespace/componentName. Some managed components restrict which @api properties are available.
Salesforce Screen Flows	Use the Flow component instead	The Flow component is purpose-built for embedding Flows with input/output variable mapping.

What doesn't work directly

Some Salesforce products still use older component frameworks or proprietary rendering:

Component type	Works?	Workaround
Aura components	No	Create a thin LWC wrapper that contains the Aura component via lightning:container or iframe, then embed the wrapper in the LWC Container.
OmniScripts (legacy Vlocity runtime)	No	If your org uses the LWC-based OmniScript runtime (available since Vlocity/Industries Winter '23), the OmniScript may be loadable as an LWC. Otherwise, wrap it in a custom LWC.
FlexCards (legacy Vlocity runtime)	No	Same approach: if your FlexCards have been migrated to the LWC runtime, they may work. Otherwise, a wrapper LWC is needed.

The wrapper pattern

When a component can't be loaded directly, the standard approach is:

1. A developer creates a minimal LWC that renders the target component internally (via <lightning-flow>, an iframe, or dynamic component creation).

2. The wrapper exposes @api properties for any data it needs from the Dynamic Component (e.g., recordId, configuration values).

3. You embed the wrapper in the LWC Container and pass data as usual.

This adds a development step, but once the wrapper exists, it behaves like any other LWC in the builder — with visibility rules, data binding, and interactions.

Info

If you're unsure whether a specific managed package component is LWC-based and exposed, check its .js-meta.xml in the package metadata, or ask the vendor. The trend across Salesforce Industries products is migrating from Aura to LWC, so components that didn't work a year ago may now work

Important Considerations

• Developer Dependency: This component relies on having a custom LWC already developed or developed by someone with LWC coding skills.

• Data Flow: Primarily designed to pass data into the LWC. If the LWC needs to communicate data back out to the Dynamic Component for other Avonni components to react to, the LWC developer would need to dispatch standard JavaScript CustomEvents, and you would need to configure appropriate event listeners or interactions if the LWC Container or parent Dynamic Component supports this (this capability may vary).

• LWC Performance: The performance of the embedded LWC is the LWC developer's responsibility.

• Styling Scope: The LWC Container styles its frame. That LWC's own CSS controls the internal appearance of the embedded LWC.

---

In Summary

The LWC Container lets you drop custom-coded LWCs into your Dynamic Component layouts. Your developer builds the LWC, you configure the data and visibility in the builder. For third-party and managed package components, the same approach applies as long as the component is a standard, exposed LWC.