--- title: "Bring Your Own (BYO): Custom Component" slug: "bring-your-own-byo-custom-component" updated: 2025-09-26T06:50:22Z published: 2025-09-26T06:50:22Z canonical: "docs.unqork.io/bring-your-own-byo-custom-component" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Bring Your Own (BYO): Custom Component > [!WARNING] > The Bring Your Own framework is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript. ## Overview Developers can build and register **custom components** that integrate seamlessly into the Unqork Designer Platform. These components must be valid [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), conform to the `UnqorkComponent` interface, and expose a model and view using named exports. > [!WARNING] > To improve security, external URLs cannot be imported into a BYO implementation file. Unqork recommends copying external source code into the implementation JavaScript file. After registering a custom component, it can be configured and rendered through the Unqork Designer Platform like any native component. ## Component Definition Defining a custom component begins with specifying its key attributes in the manifest.json file. Each entry in the components array outlines a new component that will be available in the Unqork platform. > Learn more about the component definition in our [BYO: Understanding the manifest.json File](/v1/docs/bring-your-own-byo-understanding-the-manifestjson-file) article. To register a component, define its **model** and **view** as named exports in a file called yourComponentNameHere.js. The file name must match the main field specified in the manifest.json, and the export name must match the component type defined in the same file. ```typescript export class CustomComponent extends HTMLElement {   constructor() {     super()     this.attachShadow({ mode: 'open' })   }   /**    * This is the only required method to integrate with the Unqork system    *     * @param {*} api The interface to the Unqork Runtime, used for both    * monitoring state and emitting events    */   initialize(api) {     this.config = api.state.currentState()     this.api = api;   }   /**    * This is a web component lifecycle method    *     * It's recommended for setting up initial view and events, but not required    */   connectedCallback() {     this.initialView()   }   /**    * Render initial dom structure    */   initialView() {     this.shadowRoot.innerHTML = `       

I'm a custom component

    `   } } class CustomComponentDefinition {   color = 'red';   output; } export const MyCustomComponent = {   model: async () => CustomComponentDefinition,   view: async () => CustomComponent } ``` ### State A custom component’s runtime state looks like the following: ```json {   "key": "myComponent",   "type": "byoc",   "name": "BYOC Component",   "byo": {     "componentType": "MyCustomComponent"   },   "text": "I'm custom text",   "color": "red" } ``` > [!WARNING] > Updating from [v7.22](/v1/docs/7220-platform-release-notes) to [v7.24](/v1/docs/7240-platform-release-notes) might cause issues with older custom components. The component settings model is no longer nested under the args property. It's now the top level of the component state. For example, state.color instead of state.args.color. ### Interface All custom components must implement the UnqorkComponent interface: ```typescript export interface UnqorkComponent extends HTMLElement {   initialize: (api: UnqorkAPI) => void; } ``` #### Line 2: initialize(api: UnqorkAPI): void Calls after the component is added to the DOM. Use this value to subscribe to state changes or dispatch events. > [!WARNING] > Updating from [v7.22](/v1/docs/7220-platform-release-notes) to [v7.24](/v1/docs/7240-platform-release-notes) might cause issues with older custom components. The first argument, initialConfig, has been removed. Now, the initial state is retrieved by API. For example, const state = api.state.currentState();. ### Events A component can emit events to communicate with the platform or other components: ```typescript this.api.events.emit(new CustomEvent()); ``` > To learn more about custom component events, view our [BYO: Events](/v1/docs/bring-your-own-byo-custom-events) article. ## Resources ### [Bring Your Own (BYO) Framework Landing Page](/v1/docs/bring-your-own-byo-framework-landingpage) Find all the resources needed to build your own components here. ### [Introduction to the Bring Your Own (BYO) Framework](/v1/docs/introduction-to-the-bring-your-own-byo-framework) Get started building your own custom assets, including components, events, and operations. ### [Create a BYO Package](/v1/docs/bring-your-own-byo-create-a-package) Discover the structure and content of a BYO Package ### [Understanding the manifest.json File](/v1/docs/bring-your-own-byo-understanding-the-manifestjson-file) Learn about the file's specification, component and event definitions. ### [Understanding the BYO Runtime Engine API](/v1/docs/bring-your-own-byo-understanding-runtime-engine-api) Discover the interface between your custom BYO components and the Unqork platform. ### [Custom Component SDK](/v1/docs/bring-your-own-byo-component-sdk-software-development-kit) Extend component functionality in the Unqork Designer Platform. ### [Custom Events](/v1/docs/bring-your-own-byo-custom-events) Learn more about creating custom events for use in the Operations Builder. ### [Custom Operations](/v1/docs/bring-your-own-byo-custom-operations) Learn more about creating custom operations for use in the Operations Builder.. ### [Event Payloads](/v1/docs/bring-your-own-byo-726-event-payloads) Learn more about viewing and using event payloads with the Operations Builder. ### [BYO Implementation Examples](/v1/docs/bring-your-own-byo-726-implementation-examples) Discover examples of component implementation using the Unqork Designer Platform. ### [BYO Best Practices](/v1/docs/best-practices-bring-your-own-byo-framework) Learn about best practices for implementing and using BYO assets. ### [BYO General FAQ](/v1/docs/bring-your-own-byo-general-faq-frequently-asked-questions) Learn about the Bring Your Own Framework and discover frequently asked questions. JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.