# 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.

{% hint style="warning" %}

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

Unlike the [Data LWC Container component](https://docs.avonnicomponents.com/dynamic-components/components/data-lwc-container), 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](https://docs.avonnicomponents.com/dynamic-components/components/data-lwc-container) Container component instead.
{% endhint %}

***

## Adding the LWC Container Component

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

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FqIPxg83yRcAnKf2N7aEt%2F2025-05-14_21-10-09.png?alt=media&#x26;token=f0573c60-eb3e-4603-9f49-30a6e88ec3bc" alt="" width="351"><figcaption></figcaption></figure>

***

## 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).

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FiMS4eqceMgD33wQFYmZG%2F2025-05-14_21-10-57.png?alt=media&#x26;token=a18bf73b-5d74-4b38-bbcd-ada3581e3fc8" alt="" width="320"><figcaption></figcaption></figure>

### 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

```javascript
@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**

{% hint style="success" %}

## 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
  {% endhint %}

### 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

```js
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.

{% hint style="success" %}

## 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.
  {% endhint %}

### **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**](https://docs.avonnicomponents.com/dynamic-components/getting-started/understanding-the-essentials/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`**

```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`**

```javascript
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
<?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`**

```javascript
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`**

```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.

{% hint style="info" %}

#### 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
{% endhint %}

{% hint style="warning" %}

## 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.
  {% endhint %}

***

## **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.