Overview
A registered custom code-component appears on a page through the Custom block. You add the Custom block from the block picker, point it at a component and a version, feed it data through the inspector, and handle the events it raises — exactly like configuring any other block.
The registered component is the code; the Custom block is how you place and wire it on a page.
Placing a Custom Component
Open a page in the app builder.
Open the block picker and find Custom in the block list (or search for the component's name or keywords).
Drag the Custom block onto the canvas.
In the inspector, the Component Version picker lists all registered components and their versions.
Select the component and the version you want this block to render.
Choosing Which Version Renders
The Component Version picker lists three categories of versions:
| Version option | Behavior | Use for |
Latest deployed | Follows every new production version automatically — promote a new version and the block picks it up. | Most pages — always runs the current stable release |
Specific version | Pins the block to one numbered build. A later promotion doesn't change it until you switch versions yourself. | Pages that must stay on a particular build; isolation from regressions |
Development version | Renders the live test build from the developer's Manifest URL. | Testing during development only — never use for published apps |
Warning: Switch away from the development version before publishing. Pointing a block at the live test build means end users see unreleased work and whatever the developer redeploys at that URL. Always switch to Latest deployed or a pinned version before publishing the app.
Passing Data and Handling Events
Passing data in
Feed the component whatever you bind to the block's Data property — usually an expression that references other page data. The component reads this as its input. The exact shape depends on what the component's developer designed it to accept.
Handling events
When the component reports a change or a click, the block raises:
On Change — fires when the component reports a data change
On Click — fires when the component reports a click
Wire these to actions in the Interactions panel. The component can also write back to its own state for your bindings to read.
Note: Events and data flow depend on the component's code. The block feeds data in and surfaces the events the component chooses to raise. If a handler never fires, the component may not raise that event — check with the component's developer.
Updating Component State from Actions
You can push data into a placed custom component from any action using two methods on the block:
| Method | What it does |
Update State | Writes to the component's own top-level state. |
Update Data | Writes into the component's data at specific paths using path-and-value pairs. Merges rather than replaces — setting a nested field leaves siblings untouched. Useful for form-like components that need one field patched from elsewhere on the page. |
Both are available under Trigger Component Method in any action's configuration.
Development Version Is Blocked
If the canvas shows "Custom component blocked — The dev URL {host} isn't on this app's allowlist", use the Allow & reload action on that message. It adds the host to the app's allowed list, turns on CSP enforcement, saves any unsaved page, and reloads so the new policy takes effect.
Component Has No Deployed Versions
The version picker only lists versions that exist. A freshly registered component with just a test version cannot offer a deployed version until it is promoted. Ask the component's developer to promote a production version before you need to use it in a published page.
In the meantime, you can use the development version for testing in the builder, but don't publish with it.
Frequently Asked Questions
The custom component shows a blank area. What's wrong?
Check: (1) is the Manifest URL reachable? Open it in a browser tab. (2) Is it blocked by CSP? Look for the "Custom component blocked" banner. (3) Is the development version outdated? The developer may have changed the URL. (4) Did the file checks pass when it was registered? An incomplete package can register but fail to load at runtime.
On Change never fires even though the component renders correctly. Why?
Events fire only if the component's code raises them. If the developer didn't wire an on-change event in the component's code, the block never fires it. Contact the component's developer to verify which events are implemented.
Can I bind the component's internal state to other blocks on the page?
Yes. The component can write back to its own state, and those values are exposed as block state for other bindings to read. The exact state shape depends on what the developer implemented — check with them for the available keys.
What's the safest version setting for a production page?
Use Latest deployed if you always want the newest stable build. Use a specific version if you need to isolate the page from future promotions — for example, in a regulated environment where changes must be reviewed before reaching users.
Related Pages
Custom Components Overview — the full lifecycle and two-halves model
Registering & Versioning — creating and managing versions