What Is a Custom Code-Component?
A custom code-component is a component your developers write in code and register with the platform, so builders can drop it onto a page like any built-in block. It lives as its own versioned entity — separate from any single app — with a name, one in-progress test version, and any number of promoted production versions.
Once registered, the same component can be reused across every app in the project. This is the developer path; for composing existing no-code blocks into a reusable component without code, use template components instead.
The Two Halves
These are two distinct parts of the same feature:
| Part | What it is | Where |
| Custom code-component | The registered, versioned bundle of developer code. Created and versioned in the Custom Components manager. Does not appear on any page by itself. | Applications → Custom Components manager |
| Custom block | The on-canvas block that renders one of these components on a page. It picks a version of the component, feeds it the data you bind, and exposes its events to your page. | Page builder → block picker |
One component can back many Custom blocks across many apps and pages.
The Component Lifecycle
A custom code-component moves through four stages:
Register. A developer creates the component in the Custom Components manager and gives it a name. See Registering & Versioning.
Test. The component's in-progress work is served live from a manifest URL. Developers iterate and see changes without a formal release. See Registering & Versioning.
Promote. When ready, it is packaged, uploaded, and deployed as a numbered production version — optionally tagged with release notes. See Registering & Versioning.
Use. A builder adds a Custom block to a page, picks a version, and binds data and events. See Using in the Builder.
The Manifest
Both development and production versions rely on a manifest — a small manifest.json file the developer ships with the component. It tells the platform how to load and label the component:
| Field | Required | Description |
name | Required (required) | Display name shown in the builder |
type | Required (required) | Unique type identifier. Must be unique across the project — duplicate types cause one to silently not appear. |
main | Required (required) | The component's main entry file |
style | Optional (optional) | The component's stylesheet |
icon | Optional (optional) | The component's icon shown in the picker |
keywords | Optional (optional) | Search keywords for the block picker |
Adding a Custom Component
From the Custom Components manager, click Add Component and choose a deployment mode:
| Mode | Description | Input required |
Development | Test and debug before sharing. Platform loads the component live from your local/dev URL. | Manifest URL — the URL of your local manifest file |
Production | Stable, optimized components ready for platform-wide use. | Upload a packaged .zip, with optional version tag and release notes |
When you upload a production build, the platform runs File Checks before saving — confirming the manifest file is present, the component type is defined, the UI code is included, and a component icon is available.
Pushing Data into a Custom Component
A custom component placed on a page exposes two methods you can call from any action:
Update State — writes to the component's own top-level state.
Update Data — writes into the component's data, one or more path-and-value pairs at a time. It merges rather than replaces, so setting a nested field leaves its siblings untouched.
When a Dev Component Is Blocked from Loading
If the canvas shows "Custom component blocked — The dev URL {host} isn't on this app's allowlist":
The app's Content Security Policy doesn't allow your local/dev host.
Use the Allow & reload action on that message. It adds the host to the app's allowed list and reloads the page.
Your manifest URL can now load.
Project-Level Asset
A custom code-component is a project-level asset, not part of one app. Registering it once makes it available to every app in the project. A new production version becomes available everywhere the component is used — whether that's a good thing or requires careful versioning is up to you. Pin apps to a specific version if you need to isolate them from future promotions.
Frequently Asked Questions
Who should register and manage custom components?
Custom components are the developer path — a developer writes the component code and registers it. Builders (non-developers) then place the registered component on pages using the Custom block, just like any built-in component. The developer manages versions; the builder manages placement and data binding.
What's the difference between a custom code-component and a template component?
A custom code-component is written in code (JavaScript/TypeScript) for behavior the built-in blocks can't express — a Gantt chart, a rich map, a specialized visualization. A template component is built by composing existing no-code blocks into a reusable pattern. Use code when the built-in blocks aren't enough; use a template component when they are.
Can I use a custom component before it has a production version?
Yes — place a Custom block and choose the development version. But switch to a deployed version before publishing your app, so end users don't see unreleased work or suffer from a developer's mid-day redeploy.
What happens if two custom components declare the same type in the manifest?
Only the first one loaded is registered; the second silently never appears in the block picker. Each component's type in manifest.json must be unique across the entire project.
Related Pages
Registering & Versioning — creating, testing, and promoting versions
Using in the Builder — placing and wiring a custom component on a page
Template Components Overview — the no-code alternative to custom components