--- title: "Introduction to Extensions" slug: "introduction-to-extensions" description: "Explore Unqork Extensions, enabling custom functionality in the Module Builder for enhanced module interactions and API connections." updated: 2025-10-28T13:45:01Z published: 2025-10-28T13:45:01Z canonical: "docs.unqork.io/introduction-to-extensions" --- > ## 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. # Introduction to Extensions > [!WARNING] > The Extensions feature is currently in open beta. Please contact your Unqork representative for more details and access. Vega (v2.0) **Extensions** enable Creators to build custom functionality inside the Module Builder. Extensions are modules that perform Creator-customized actions to a module that’s currently being edited on the Module Builder’s canvas. Like standard modules, extensions can perform complex logic, connect to APIs, or interact directly with the UDesigner Module Builder. Examples of extensions that Creators can build include: - Retrieve, modify, and update component JSON data. For example, mass formatting of Property IDs. - Implement an API that can interact with module component data. - Check for component best practices. For example, verifying all components are set to **Manual** instead of **Watch**. Unqork environments can have any number of extensions, and extensions are available to all applications and modules in the environment. > [!WARNING] > The Extensions feature is intended for developers who have a strong understanding of the Unqork Designer Platform, [Operations Builder](/v1/docs/introduction-to-the-operations-builder), and [Vega (v2.0) Runtime](/v1/docs/introduction-to-vega). ## How Extensions Work Extensions operate in an isolated Vega (v2.0) runtime inside the UDesigner Module Builder. This runtime acts as a secure container, letting an extension interact with the module currently being edited. An extension can also function as a standalone tool if no interaction with the current module is required. Additionally, Creators should note the extension's startup behavior: whenever an extension is loaded or reloaded, any [Initializer](/v1/docs/initializer-component) component configured to trigger on `New Submission` executes automatically. > Creators can learn how to use extensions in our [Module Extensions Drawer](/v1/docs/module-extensions) article. ### Create and Size an Extension Module Creators can create or convert a module into an extension module using tags. Tags are assigned during the creation of a new module or by using the **Settings** menu in the Module Builder. #### The `extension` Tag The `extension` tag converts the current module to an extension module. Extension modules display in the extensions drawer for all Creators in the environment. > RBAC (role-based access control) for extensions is not supported at this time. #### Extension Sizing Tags Creators can control the size of an extension’s modal window by adding a size tag to the module. For example, to create a medium-sized extension modal, you would assign the module the `extension` and `size:-medium` tags. The available size options include: - `size:-small` - `size:-medium` - `size:-large` - `size:-xlarge` #### Converting a Module to an Extension in the Module Builder While Creators can convert any module into an extension using the extension tag. Unqork recommends using the [Extension Layout Starter](/v1/docs/extension-start-kit-template#how-the-template-works) module for configuring new extensions. This module includes the minimum components required to create a functioning extension. To convert an existing module to an extension module: 1. In the Module Builder, click the ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/image(33).png?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A16Z&se=2026-11-09T04%3A51%3A16Z&sr=c&sp=r&sig=XaBviAyTLS66HA5AWq7LS1dSAaaZi2DdzLkWc0WtFEg%3D) (**ellipsis**) button. 2. Click **Module Settings**. 3. Scroll down to the **Tags** field. 4. Click the **Tags** field, enter or select `extension`. 5. Click on the **Tags** field again, enter a size tag using the [Sizing an Extension](/v1/docs/introduction-to-extensions#sizing-an-extension) list. For example: `size:-medium`. 6. Click **Save & Close**. The module now functions as an extension and displays in the [Extension drawer](/v1/docs/module-extensions). ### How Extensions Interact With the Module Builder When an interaction with the Module Builder is required, an extension emits an `EXTENSION_EVENT`. While this event type is generic, its `payload` must specify one of the predefined actions that UDesigner can perform. View a list of predefined actions in the [Events and Keywords Reference Lists](/v1/docs/introduction-to-extensions#events-and-keywords-reference-lists) section. > Learn more about events in our [Introduction to Operations Builder](/v1/docs/introduction-to-the-operations-builder#understanding-events) article. ### **Emitting the Extension Event** To trigger an action, emit an `EXTENSION_EVENT` using the [Events and Operations Builder](/v1/docs/operations-builder) or a logic component like an [Initializer](/v1/docs/initializer-component) component. Let’s look at the structure of a Vega (v2.0) `EMIT_EVENT` operation: ```json  {    "type": "EMIT_EVENT",    "options": {      "event": "EXTENSION_EVENT",      "payload": {        "event": "EXTENSION_READY_FOR_COMPONENTS",        "includeOperationContext": true      }    } } ``` 1. The [operation](/v1/docs/introduction-to-the-operations-builder#understanding-operations) type is `EMIT_EVENT`. 2. Inside the `options` object, the `event` property is set to the string `EXTENSION_EVENT`. This tells the UDesigner platform that the event is intended for the extension. 3. The `payload` object within `options` contains its own `event` property. Set this to the name of the specific action you want to run. > View a list of possible actions in the [Extension Events Reference List](/v1/docs/introduction-to-extensions#extension-events-reference-list) section. 4. The `payload` object should also include `includeOperationContext: true` when your extension is sending data to UDesigner or when using the [postEventTriggerKey](/v1/docs/introduction-to-extensions#the-posteventtriggerkey-pattern) pattern. ### **Using the GET_PROPERTY Operation** The `GET_PROPERTY` operation is a crucial part of the Extension toolkit when sending data or defining post-event triggers. It retrieves a value from a component and adds that data to the operation context. Let’s look at the structure of a Vega (v2.0) `GET_PROPERTY` operation: ```json  {    "name": "dataOut",    "type": "GET_PROPERTY",    "options": {      "targetKey": ["postEventTriggerKey"],      "property": "value"    }  } ``` 1. The [operation](/v1/docs/introduction-to-the-operations-builder#understanding-operations) type is `GET_PROPERTY`. 2. Inside the `options` object, the `targetKey` accepts an array of Property IDs. This enables the retrieval of values from multiple components in a single operation. For example, `targetKey: ["componentsOut", "postEventTriggerKey"]`. The operation’s purpose is to act as temporary storage that exists for the duration of a single execution of a chain of operations. By adding data to this context, you make it available for any subsequent operations in the same chain. This is required for sending data to UDesigner, and for using the [postEventTriggerKey](/v1/docs/introduction-to-extensions#the-posteventtriggerkey-pattern) pattern. ### Handling Extension Event Timing and Post-Event Triggers Sometimes, you need to ensure that logic runs only after an extension event has fully completed and all related data is available. There are two primary methods for handling this process: #### The Watcher Pattern You can configure a logic component, like an [Initializer](/v1/docs/initializer-component) component, that watches the `componentsIn` **Hidden** component field. That way, the logic component triggers only when the `componentsIn` field changes. Doing so guarantees that extension module logic runs after the data is retrieved. #### The `postEventTriggerKey` Pattern A more direct method is to use the `postEventTriggerKey` feature, which lets you specify a component that UDesigner will execute automatically after the event logic completes. To use the `postEventTriggerKey` pattern: 1. Create a Hidden component in your extension module with the Property ID of `postEventTriggerKey`. 2. In the **Default Value** field, enter the Property ID of the component you want to trigger after the event completes. For example, the Property ID of an [Initializer](/v1/docs/initializer-component) or [Calculator](/v1/docs/calculator-component) component. 3. In the [operation](/v1/docs/introduction-to-the-operations-builder#understanding-operations) logic that emits the event, use a `GET_PROPERTY` operation to load the value of `postEventTriggerKey` into the operation context *before* the `EMIT_EVENT` operation. For example: ```json [  {    "name": "dataOut",    "type": "GET_PROPERTY",    "options": {      "targetKey": ["postEventTriggerKey"],      "property": "value"    }  },  {    "type": "EMIT_EVENT",    "options": {      "event": "EXTENSION_EVENT",      "payload": {        "event": "EXTENSION_READY_FOR_COMPONENTS_FLAT",        "includeOperationContext": true      }    }  } ] ``` 4. You must also set `includeOperationContext` to `true` in the event’s payload, so UDesigner can process the post-event trigger. > [!WARNING] > This pattern works for all extension events except `EXTENSION_READY_TO_CLOSE`. ### Data Flow For the extension's data features to work, the necessary data-handling components must already exist in your extension module. These components use specific, reserved Property IDs. - **Receiving Data**: When you request components from the canvas, UDesigner places the component JSON data into a Hidden component with the Property ID of `componentsIn`. - **Sending Data**: When you want to update or replace components on the canvas, you must place your new component JSON data into a Hidden component with the Property ID of `componentsOut` before emitting the event. - **Displaying a Toast**: To show a toast notification, you must place the message string in a component with the Property ID of `toastContent`. View the **Keyword List** in the section below for more details on reserved keywords. ## Events and Keywords Reference Lists Click on the tabs below to learn more about the Extension feature’s specific Events, Operations, and Property IDs: Events ListKeyword List ## Extension Events Reference List The Extensions feature uses Vega (v2.0) events to send and retrieve data from the UDesigner Module Builder. Review the [How Extensions Interact With the Module Builder](/v1/docs/introduction-to-extensions#how-extensions-work) section for more details on how to use these events. | Events | Description | Function | Usage | | --- | --- | --- | --- | | `EXTENSION_READY_FOR_COMPONENTS` | Informs the Module Builder that the extension is ready to receive the module’s component data. | Retrieves module’s JSON data, retaining the parent/child hierarchy. This event stores retrieved data in the extension’s `componentsIn` **Hidden** component. | Use this event to view the unmodified structural layout of a module’s component data. | | `EXTENSION_READY_FOR_COMPONENTS_FLAT` | Informs the Module Builder that the extension is ready to receive the module’s unnested component data. | Retrieves module’s JSON data and unnests (flattens) its structure. This event stores retrieved data in the extension’s `componentsIn` **Hidden** component. | Use this event for updating component data. | | `EXTENSION_READY_TO_REPLACE_COMPONENTS` | Instructs the Module Builder to overwrite the component data currently on the canvas. | Deletes all existing component data and replaces it with the data provided in the extension’s `componentsIn` **Hidden** component. | Use this event for large-scale changes or for any modifications involving a component's children. The `includeOperationContext` is required so UDesigner can find the `componentsOut` data source. | | `EXTENSION_READY_TO_UPDATE_COMPONENTS` | Instructs the Module Builder to update one or more existing components currently on the canvas. | Iterates through the canvas’s component data using their `componentId` and updates the properties. This event updates the canvas using the data in the extension’s `componentsIn` **Hidden** component. | | | `EXTENSION_READY_TO_SHOW_TOAST` | Instructs the Module Builder to display a pop-up notification (toast). | Triggers the UDesigner to display a toast message. This event displays the value contained in extension’s `toastContent` **Hidden** component. | Use this event to provide feedback to the Creator. The `includeOperationContext` is required so UDesigner can find the `toastContent` data source. | | `EXTENSION_READY_TO_CLOSE` | Instructs the Module Builder to close the extension interface. | Triggers the UDesigner to close the current extension modal. | | #### Reserved Keywords Reference List Unlike regular modules, Extension modules use reserved Property IDs (Keywords) for retrieving and exporting module data. These Property IDs are assigned to [Hidden components](/v1/docs/hidden-component). Creators building extensions should avoid from modifying keywords for anything but their intended purpose. Reserved keywords include: | Keyword (Property ID) | Function | | --- | --- | | `componentsIn` | Stores component JSON data retrieved from the UDesigner canvas. Data is retrieved from the canvas using an Initializer component and the `EXTENSION_READY_FOR_COMPONENTS` or `EXTENSION_READY_FOR_COMPONENTS_FLAT` events | | `componentsOut` | Stores component JSON data ready to be emitted back out to the UDesigner canvas. Data sent to this component emits from the `XTENSION_READY_TO_REPLACE_COMPONENTS` or `EXTENSION_READY_TO_REPLACE_COMPONENTS` events. | | `toastContent` | Stores a text string value for displaying at the button of the UDesigner Module Builder. Data sent to this component emits from the `EXTENSION_READY_TO_SHOW_TOAST` event. | ## Styling an Extension Unqork provides an Extension Starter Kit Template to help apply a consistent look and feel that matches the UDesigner platform. Creators can enhance this layout using the provided [Extensions Design System](/v1/docs/extension-start-kit-template#how-the-template-works) module. ### Getting Started with Starter Kits The Extension Starter Kit Template can be found on the [Unqork Marketplace](https://marketplace.unqork.io/app/marketplace#/display/listing?id=68a33fe8fbde1604c6d31841). This pack includes three extension modules to get you started: - **Extension Layout Starter**: This extension provides the standard layout for an extension, which has a content area and an action section. - **Extensions Design System**: This extension provides you with the design tokens, or custom classes for the extension’s design and layout. - **Extension Interaction Examples**: This extension showcases how all the different extension events and interactions work in practice. You can run these as extensions to see what the design tokens do visually, and you can also look at their configuration to see how to achieve the intended layout. #### Layout and Spacing Extension layouts are typically built with [Field Group](/v1/docs/field-group-component) components, and the custom class field is set to a specific design token. Nesting Field Groups with the correct custom classes defines layout and spacing. A key part of the layout is the actions area. While users can always exit the extension by clicking the **X** button in the header, it is a best practice to also include a **Close** or **Finish** button in your defined actions. You can implement this by adding a Button component that triggers the `EXTENSION_READY_TO_CLOSE` event. #### Styling Limitations At this point, using your own custom stylesheet in an extension is not supported. This limitation ensures all extensions fit seamlessly in the look and feel of UDesigner. For text styling, like changing text size for headers, the recommended approach is to use an [HTML Element](/v1/docs/html-element-component) component and standard header tags. For example, `<h1>`, `<h2>`. > Discover how to install and use the Extension Starter Kit Template in our [Marketplace: Extension Starter Kit](/v1/docs/extension-start-kit-template) article. The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. A Property ID is the unique field ID used by Unqork to track and link components in your module. Triggers activate another component when certain requirements are met. Trigger types include Concurrent, Post, and Error. Some components do not have the ability to trigger others. RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. A modal is a window that appears on top of the content you are currently viewing. An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. is a codeless and interoperable Unqork IDE (integrated development environment) with a new and improved user experience that allows for a seamless transition for all your applications. It features a modern user interface with new personalization, collaboration, and configuration experiences. A Property ID is the unique field ID used by Unqork to track and link components in your module. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. ## Related - [Module Extensions Drawer](/module-extensions.md) - [Extension Starter Kit Template](/extension-start-kit-template.md)