--- title: "Embedded UI: Understanding the EmbeddedModule Interface" slug: "embedded-ui-understanding-the-embeddedmodule-interface" updated: 2025-09-26T00:04:56Z published: 2025-09-26T00:04:56Z canonical: "docs.unqork.io/embedded-ui-understanding-the-embeddedmodule-interface" --- > ## 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. # Embedded UI: Understanding the EmbeddedModule Interface > [!WARNING] > The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript. ## Overview The **Embedded** **Module** **interface** provides Creators with methods to interact with an Unqork module in real time. Creators can use the interface to execute actions, send and retrieve data, or respond to events in the module. > [!NOTE] > Embedded UI is currently in open beta. Please contact your Unqork representative for more details and access. ## Understanding the `EmbeddedModule` Interface The `EmbeddedModule` interface consists of the following: ```plaintext interface EmbeddedModule {   moduleId: string   ready(callback: () => void): Promise   on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void   send(event: "submission_data" | "operation", data: unknown, context?: any): Promise   get(data: RuntimeDataType): any   validate(): Promise   swapModule(module: AnyModuleDefinition, submissionData?: SubmissionData): Promise   registerSubmissionHandler(handler: ModuleSubmissionHandler): void   unregisterSubmissionHandler(): void   registerValidationHandler(handler: ModuleValidationHandler): void   unregisterValidationHandler(): void   removeSubscriptions(): void   destroy(): Promise } ``` ### Methods of the `EmbeddedModule` Interface All examples of `module.<method>` assume the module is a declared variable assigned to the value of `runtime.mountModule`. If a different variable name is used, like `unqorkModule`, then the reference becomes `unqorkModule.<method>`. #### Line 3: `ready(callback: () => void): Promise<void>` Registers a callback function to execute when the module is fully initialized and ready for interaction. ##### Args - `callback`: The function to be invoked once the module is ready. For example: ```plaintext module.ready(() => { console.log("The module is ready! You can now interact with it."); }); ``` #### Line: 4: `on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void` Subscribes to events occurring in the runtime, and responds with a provided callback. ##### Args - `'system.submission.saved'`: Triggered when the module is submitted and saved. - `'components.myActionBtn.click'`: Triggered when a component with the key `myActionBtn` is clicked. For example: ```plaintext // Respond to a successful submission module.on('system.submission.saved', (values) => {   console.log('Submission saved with values:', values); }); // Respond to a button click within the module module.on('components.myActionBtn.click', () => {   // Trigger an action in your external application. }); ``` ##### Available Events | Event Type Name | Event Type Enum | | --- | --- | | RUNTIME_DATA | runtime_data | | SUBMISSION_DATA | submission_data | | VALIDATION_RESULTS | validation_results | #### Line 5: `send(event: "submission_data" | "operation", data: unknown, context?: any): Promise<void>` Executes an action in the module by sending it data or an operation. ##### Args - `event`: The type of action to perform. For example, `'submission_data'` or `'operation'`. - `data`: The payload for the action. - `context`: `OPTIONAL` A context object for the action. ```plaintext // Send data to a module component module.send('submission_data', {   // Keys here should correspond to component keys.   firstName: 'Alex',   email: 'alex@example.com', }); // or // Execute an operation to set a component property module.send('operation', {   "type": "SET_PROPERTY",   "options": {     "targetKey": "firstName",     "property": "display.hidden",     "value": false,   } }) ``` #### Line 6: `get(data: RuntimeDataType): any` Retrieves the internal state or data of the module at the current time. **Returns**: The requested runtime data. ##### Arg - `data`: The type of runtime data to retrieve. For example: ```plaintext const currentValues = module.get('runtime_data') ``` ##### Available Runtime Data Types | Runtime Data Type | Runtime Data Type Enum | | --- | --- | | runtime_data | RUNTIME_DATA | | submission_data | SUBMISSION_DATA | | validation_results | VALIDATION_RESULTS | #### Line 7: `validate(): Promise<void>` Triggers a full validation of the module. This method does not display validation errors on untouched components. **Returns**: A promise that resolves when validation is complete. The resolved value contains the validation results. For example: ```plaintext const {isModuleValid, moduleErrors} = await module.validate() ``` #### Line 8: `registerSubmissionHandler(handler: ModuleSubmissionHandler): void` Replaces the module's default submission behavior with a custom handler. The default behavior stores the data in a submission collection. When a custom handler is provided, this default action is not performed. ##### Arg - `handler`: A function that receives the module's ID and data to submit. It should return a `Promise` that resolves to a `SubmissionResponse` object containing a unique ID, which is used as the `submissionId` for the last saved submission. The handler can also return `undefined` if no ID is needed. `ModuleSubmissionHandler` type definition: ```plaintext type ModuleSubmissionHandler = (   moduleId: string,   data: Record, ) => Promise type SubmissionResponse = {   id: string } ``` JavaScript example: ```plaintext module.registerSubmissionHandler((moduleId, dataToSubmit) => {   console.log('Custom handler is processing submission for module:', moduleId);   // Send data to a custom API here. }) ``` #### Line 10: `unregisterSubmissionHandler(): void` Removes any previously registered custom submission handler, reverting to the default submission behavior. For example: ```plaintext module.unregisterSubmissionHandler() ``` #### Line 11: `registerValidationHandler(handler: ModuleValidationHandler): void` Registers a custom handler to intercept validation results, letting you customize the user experience. ##### Arg - `handler`: A function that receives the module's ID and validation results. Handler Return Values: - **No return value**: The standard validation and errors work as normal. - `false`: Clears all current validation errors for the embedded module. - **Updated results**: You can return a modified `ModuleValidationResult` object to apply custom validation from an external source, like an API. `ModuleValidationHandler` type definition: ```plaintext type ModuleValidationHandler = (moduleId: string, results: ModuleValidationResult) => ModuleValidationResult | false class ModuleValidationResult {   isValid?: boolean   results: Record } class ValidationResult {   isValid?: boolean | null = null   errors?: ValidationError[] } export class ValidationError {   type: ValidationRuleTypes   message?: string } ``` JavaScript example: ```plaintext module.registerValidationHandler((moduleId, results) => { myApp.showErrors(results); return results; }); ``` #### Line 12: `unregisterValidationHandler(): void` Removes any previously registered custom validation handlers, reverting to the default validation behavior. For example: ```plaintext module.unregisterValidationHandler() ``` #### Line 13: `removeSubscriptions(): void` Destroys all event subscriptions that were created by the on() method. For example: ```plaintext module.removeSubscriptions() ``` #### Line 14: `destroy(): Promise<void>` Removes the module and its state from the DOM. > [!CAUTION] > Data does not preserve unless it's stored or submitted beforehand. For example: ```plaintext module.destroy(); ``` ## Resources ### [Introduction to the Embedded User Interface (UI)](/v1/docs/introduction-to-the-embedded-user-interface-ui) Learn how the Embedded UI feature works and discover frequently asked questions (FAQ). ### [How to: Embed Unqork in an External Application](/v1/docs/embedded-ui-how-to-embed-unqork-in-an-external-application) View the methods that enable you to interact with an Unqork module in real time. ### [Understand the embedded.js File](/v1/docs/embedded-ui-understanding-the-embeddedjs-file) Review the script that embeds the runtime API into an external application web page. ### [Examples of Embedded UI Modules](/v1/docs/embedded-ui-example-embedded-modules) Discover examples of embedded single or multi-modules. JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. In JavaScript, a method is a function that is associated with an object. It is essentially a property of an object whose value is a function. Methods define actions or operations that can be performed on the object they belong to. 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. 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.