Custom Element

Project type: customElement · Reference version: 27.0.29

Use Custom Element to embed a local HTML component, such as a specialized control or spatial viewer. Each component lives in elements/<id>/ with its HTML, JavaScript, CSS, and other dependencies. The editor renders it in an iframe; a manifest.json can connect its props and events to AVstudio values and actions.

Add a component

1. Create elements/room-control/ inside the AVstudio project.
2. Put the component's entry document at elements/room-control/index.html and keep its dependencies beside it. Relative asset references resolve within this folder, independently of assets/.
3. Open the host page and its Add element picker. The watched folder appears under Custom Elements automatically; select it and place the control in a container.
4. Select the control and confirm its component reference in Element Properties. Set width and height for the intended layout; the template is 300 × 200 px.
5. Save and test in Live Preview. Pointer input on the design canvas selects/drags the wrapper; interaction inside the component belongs to the running preview.

The saved element uses customElementId: "room-control". A root index.html is preferred; otherwise discovery uses the shallowest, then alphabetically first HTML file in that component tree. Keep external dependencies local when their license and distribution allow it so offline use and exported builds retain them.

Declare props and events

A component renders as a static frame without a manifest. To connect it to application state, place a manifest.json next to its entry HTML document with format: "avstudio-component/v1".

Contract part	Purpose
props	Named boolean, number, or string values supplied by the host; bindable props appear in the sidebar.
Prop hook	Apply a value through a DOM property/attribute, a custom event, or a toggle click when state differs.
events	Named component gestures with none, digital, analog, or serial payloads.
Event hook	Observe DOM events, attribute mutations, window events, or filtered messages.
Event prop	Link a value-change event to the prop it updates.

Use stable selectors and the component's actual state/event surface. The bundled avstudio-custom-element AI guide covers contract analysis and adapters for components whose state cannot be read or written through standard hooks.

1. Select the inserted component. Its Content section lists the manifest's props and any validation issues.
2. Bind a prop to a test variable, page parameter, datasource value, or feedback. Saved values live in propValues under the prop name.
3. Create an action with On Change, Before Change, or After Change, then choose the manifest event in Event (attachedEventName).
4. For a state-bearing control, link its event to its prop in the manifest and configure the action to update the intended application value.
5. Save and test in both directions: component interaction updates application state, and an external state update reaches the component.

Linked props update optimistically and then follow the bound value, as value controls do. An unbound prop retains its last reported value. An invalid manifest leaves static rendering available and shows issues in the sidebar; fix those issues before expecting bindings or events to work.

Layout, runtime, and delivery

The wrapper supports normal sizing, positioning, background layers, border, padding, visibility, modes, and animations. In runtime, clicks inside the iframe belong to the component; wrapper click actions apply to its padding area.

Custom-element scripts can call the JavaScript runtime API. The injected bridge delegates that API to the host project. The local component files are included in builds; remote assets and services still require access from the final device.

Run Health Check, inspect manifest issues, and test component loading, props, event payloads, feedback, and target-device behavior. A rendered static component alone does not verify its integration.