diff --git a/docs/guides/custom-components.md b/docs/guides/custom-components.md index 9582021f..307f722c 100644 --- a/docs/guides/custom-components.md +++ b/docs/guides/custom-components.md @@ -25,6 +25,31 @@ You register entire catalogs with your client application, not individual compon 4. **Agent Selects Catalog**: The agent chooses a catalog for a given UI surface. 5. **Agent Generates UI**: The agent generates `surfaceUpdate` messages using components from that catalog by name. +## Enabling Custom Components on the Surface + +When using the `` component, you must enable custom elements rendering by setting the `enableCustomElements` property to `true`. This allows custom components registered via the component registry to be rendered. + +### Web (Lit) + +```typescript +// Get reference to the surface element +const surfaceElement = document.querySelector('a2ui-surface'); + +// Enable custom elements +surfaceElement.enableCustomElements = true; + +// Set other required properties +surfaceElement.surfaceId = 'main'; +surfaceElement.surface = surface; +surfaceElement.processor = processor; +``` + +**Important**: Without setting `enableCustomElements = true`, custom components will not render, even if they are properly registered in the component registry. + +### Why This is Required + +The A2UI `Surface` component wraps the `Root` component, which handles the actual rendering. The `enableCustomElements` property controls whether the Root component should look up and instantiate custom elements from the component registry. By default, this is `false` to ensure only standard A2UI components are rendered unless explicitly enabled. + ## Defining Custom Catalogs TODO: Add detailed guide for defining custom catalogs for each platform. diff --git a/renderers/lit/src/0.8/ui/surface.ts b/renderers/lit/src/0.8/ui/surface.ts index f11af658..d44fe03d 100644 --- a/renderers/lit/src/0.8/ui/surface.ts +++ b/renderers/lit/src/0.8/ui/surface.ts @@ -32,6 +32,9 @@ export class Surface extends Root { @property() accessor processor: A2uiMessageProcessor | null = null; + @property({ type: Boolean }) + accessor enableCustomElements = false; + static styles = [ css` :host { @@ -118,6 +121,7 @@ export class Surface extends Root { style=${styleMap(styles)} .surfaceId=${this.surfaceId} .processor=${this.processor} + .enableCustomElements=${this.enableCustomElements} .childComponents=${this.surface?.componentTree ? [this.surface.componentTree] : null}