> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/lwc-container.md).

# LWC Container

The **LWC Container** lets you place custom Lightning Web Components (LWCs), built by developers, directly on your Dynamic Component canvas. Use it to embed any standard, exposed LWC — passing data into its `@api` properties and wiring its custom events to builder interactions.

## Overview

The LWC Container renders an arbitrary Lightning Web Component by name. You supply the component's API name, pass input properties from your Dynamic Component's resources (Variables, Constants, Formulas, or attributes of other Avonni components), and optionally map custom events fired by the inner LWC to builder interactions.

{% hint style="warning" %}
**Choosing the Right LWC Container: Avonni Data LWC Container vs. LWC Container**

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

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

<figure><img src="/files/0Vlec3vwSD7W3UH1H1H5" alt="" width="351"><figcaption></figcaption></figure>

## Configuration

To configure the LWC Container, select it on the canvas. The configuration panel opens on the right. The sections below mirror the properties panel from top to bottom.

### Properties

#### LWC Name

Enter the API name of the Lightning Web Component you want to embed, including its namespace (for example, `c/myCustomCardList` or `yourNamespace/specialDisplay`). This field accepts static text as well as dynamic expressions from your Dynamic Component resources.

<figure><img src="/files/DnCiIMRe7hyPZ0RWCLG4" alt="" width="320"><figcaption></figcaption></figure>

#### LWC Attributes

Requires: **LWC Name** to be set.

Pass values from your Dynamic Component directly into the `@api` properties of the inner LWC. Each entry has a **Name** (the exact `@api` property name on your LWC, case-sensitive) and a **Value** (any resource from your Dynamic Component: a Variable, Constant, Formula, component attribute, or global variable such as `$Component.recordId`).

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

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

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

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

#### Is Builder Attribute Name

Requires: **LWC Name** to be set. Advanced option.

Name of the `@api` attribute on the inner LWC that receives the `isBuilder` flag. Defaults to `isBuilder`. When the LWC is displayed inside the Component Builder, this attribute is set to `true`, letting your developer render a simplified placeholder or skip unnecessary data fetching at design time.

#### Is Preview Attribute Name

Requires: **LWC Name** to be set. Advanced option.

Name of the `@api` attribute on the inner LWC that receives the `isPreview` flag. Defaults to `isPreview`. When the LWC is displayed in the Dynamic Component's Preview mode, this attribute is set to `true`, allowing the developer to show sample data and avoid live API calls during preview.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

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

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

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the LWC Container. Configure them from the **Interactions** tab of the Edit LWC Container panel.

### Custom Interactions

Fires when the inner LWC dispatches a custom event whose name matches one of the configured entries in **Custom Interactions**. Add one entry per event name (for example, `refreshTimeline` or `showFormModal`), then choose the builder action to execute. The event name must exactly match the one dispatched by the LWC (case-sensitive).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/lwc-container.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.