--- title: "Using Smart Components in a Module" slug: "using-smart-components-in-a-module" tags: ["smart-components", "module-builder", "unqorkai"] status: "update" updated: 2026-10-21T18:57:41Z published: 2026-10-21T18:57:41Z canonical: "docs.unqork.io/using-smart-components-in-a-module" --- > ## 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. # Using Smart Components in a Module Smart Components are added and configured in the Module Builder the same way as any standard component. The Properties panel is driven by what the component declares in its interface, not authored per usage. ## Adding Smart Components to the Canvas Public Smart Components appear in the component tray under their assigned category (Primary Fields, Secondary Fields, and so on). Components with no assigned category appear under **Uncategorized**. Select a component from the tray to add it to the canvas. Each Smart Component on the canvas displays its type (UI, Logic, or Query) and component name. ## Properties Panel Selecting a Smart Component on the canvas opens the Properties panel. The header row includes icon buttons for Notes and Tags, and a menu for Permissions. These work the same way as any standard component. See [Component General Settings](/unqorkai/docs/component-general-settings) for details. Selecting the component name next to **COMPONENT** in the Properties panel header opens the [Focused Component View](/unqorkai/docs/smart-component-editor#focused-component-view), a full-panel overlay. Logic Smart Components show their logic in the **Definition** area. Public components display **Duplicate** and **Edit Definition**. Private components display **Make Public**. - **Edit Definition** opens the component in the Smart Components Hub. Without update permission, the button reads **View Definition**. - **Duplicate** creates a Private copy for that module. It is hidden in view mode and unavailable while a draft is open on the component. A banner on Public components states: "Public Smart Components cannot be edited inside a module — Duplicate it into a private copy, or Edit Definition in the Smart Components Hub." ## Component Settings Every Smart Component on the canvas has component-level settings that define how it integrates with the module. | Setting | Available for | Description | | --- | --- | --- | | **Property ID** | All types | The component's identifier in the module. Other components reference this ID and actions target it. Components inside the Smart Component do not automatically use this Property ID; each component's data is wired independently. | | **Store Data in Database** | UI only | When set to **ON**, data stored under the Property ID persists with the submission. | | **Theme Mode** | UI only | Sets the color scheme for this component: **Light**, **Dark**, or **System** (follows the end-user's device preference). Theme Mode works whether or not the application has a Linked Theme configured; it only selects which variant to render. The theme that supplies the colors is linked to the application's style, not set here. See [Linking a Theme](/unqorkai/docs/style-administration#linking-a-theme). | Permissions are component-level. The Permissions menu controls access to the component as a whole. Individual components inside cannot have separate permissions. If a component needs different permissions from the rest, it must be its own Smart Component with its own Property ID. ## UI Smart Component Sections The Properties panel for a UI Smart Component has three sections. | Section | Description | | --- | --- | | **Configuration** | One field for each input the component declares. Accepts a static value or a reference to another component on the module. | | **Appearance** | Contains the **Theme Mode** setting — sets the color scheme for this component: **Light**, **Dark**, or **System**. | | **Data** | Contains the **Store Data in Database** toggle — when set to **ON**, data stored under the Property ID persists with the submission. | ## Component Updates When a Smart Component used in a module has a newer published definition, a banner displays: "Smart Components have changed. Check your configuration still works with the current version, then save this module — or mark the updates as reviewed if nothing needs changing." The module always renders the latest published definition. There is no version pinning. The banner clears in two ways: save the module, or select **Mark as Reviewed**. **Mark as Reviewed** records the current versions as reviewed without saving the module or creating a revision. To hide the banner without recording a review, select **×** in the corner. The banner stays hidden until you leave the module. A publish that updates a component not already flagged shows it again. ## Configuring Input Values The **Configuration** section displays one field for each input the component declares. Every field accepts one of the following: - **Static value**: A fixed value set directly in the field. - **Reference**: A pointer to another component's value on the module. Select the reference toggle on the field and choose the source component. The available fields and their types are set by the component's interface. Adding or removing fields requires editing the component definition in the Smart Component Editor. ## Wiring Logic Smart Components Logic Smart Components have no visual presence on the canvas. They run when triggered and return output data. After configuring input values in the **Configuration** section, use the **Outputs** section to bind the component's results to other components on the module. The **Triggers** section includes the following field. | Field | Description | | --- | --- | | **Trigger Type** | **Manual**: runs only when another component triggers it. **Watch**: also runs when its inputs change. | ## Wiring Query Smart Components Query Smart Components work like a Plug-In component. The query runs only when triggered, never automatically. Use the **Outputs** section to bind the query's results to components on the module. The **Triggers** section includes the following fields. | Field | Description | | --- | --- | | **Trigger Type** | **Manual**: runs only when another component triggers it. **Watch**: also runs when its inputs change. | | **Set Debounce** | Displays when Trigger Type is **Watch**. Milliseconds to wait after an input change before re-running the query. Default is 500. | | **Triggered By** | Lists the components that fire this query. The wiring lives on the triggering component — a Button's Click Trigger or an Initializer — not here. | | **Post Trigger** | The component triggered after the query completes successfully. | | **Error Trigger** | The component triggered if the query fails. | ## Targeting Smart Components from Logic The platform can only see and act on the Smart Component as a whole, not the individual components inside it. Actions (**Hidden**, **Visible**, **Clear**, **Trigger**) apply to the entire component. Individual components inside cannot be named, hidden, triggered, or targeted from outside. If a piece of logic must target a specific component independently, that component must be its own Smart Component with its own Property ID. **Setting a value** works differently. Setting a value on a Smart Component writes to submission data at the specified location; it does not act on the component directly. Whether anything changes visually depends on whether a component inside is reading from that same data location. See [Smart Component Output Type Compatibility](/unqorkai/docs/smart-component-output-type-compatibility) for the full list of output types that work on Smart Components and which are silently ignored. > [!NOTE] > Two patterns that work with standard components are not recommended with Smart Components. **Dynamic Refresh** causes silent failures when the targeted component cannot be refreshed, and Smart Component-heavy modules accumulate duplicate Property IDs that make refresh unpredictable. **Imported Modules** are copied structures that can drift from their source; Smart Component references (by ID, updated in one place) are the better . Both features remain active in the platform. ## Build Agent Limitations The Build Agent creates Smart Components as Private components; the Focused Component View for the created component shows **Make Public**. The Build Agent cannot change a Public component's definition. When it attempts this, it explains that Public components can only be changed in the Hub and offers **Duplicate** or **Edit Definition** instead. The agent never acquires the module lock. When the current module is in Viewing mode, the lock card action reads "Switch to Editing and retry." When the module is in a different application, the card offers to go there and take the editing lock. When another user holds the lock, the agent cannot proceed and no recovery option appears. --- **Changelog** | Date | Change | | --- | --- | | 2026-10-20 | Renamed Configuration, Outputs, and Triggers from tabs to sections; clarified the Focused Component View entry point and actions; added UI Smart Component Sections, Component Updates, and Build Agent Limitations; added Trigger Type, Set Debounce, and Triggered By fields; added a Dynamic Refresh and Imported Modules note; clarified that Theme Mode works without a Linked Theme. | | 2026-10-15 | Clarified that Theme Mode selects between the light and dark values of the theme linked to the application's style. | | 2026-09-10 | Tech accuracy pass — corrected tray section name (category-based, not "Smart Components"); corrected Notes/Tags/Permissions from tabs to icon buttons/menu; corrected "Theme" → "Theme Mode"; corrected "General tab" → "Configuration tab"; removed legacy Output Target and retired Query Pipeline section; corrected action names (Hidden/Visible, not hide/show); removed "output triggers" for Logic SCs. | | 2026-09-10 | Rewrote for 9.0 — removed "block" terminology; tightened paragraphs; improved headings; updated Focused Component View reference. | | 2026-07-29 | Added Block Settings section and Targeting from Other Components section. | | 2026-07-28 | Initial draft. | The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application. A Property ID is the unique field ID used by Unqork to track and link components in your module. End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. Rendering is the process of loading components and displaying the final result on the front-end screen. Rendering is the process of loading components and displaying the final result on the front-end screen. Enter outputs components and actions you want the component to perform. Deteremines how the component triggers. A query lets you retrieve, access, manipulate, and delete data in a database. To execute or perform a a task. In the Operations builder, Events fire (execute) one, or multiple Operations. The Post Trigger value fires after a component has completed its action. For example, post triggering a component to display the data received from a Plug-In component's API call. A Property ID is the unique field ID used by Unqork to track and link components in your module. A data structure is the design used for organizing, using, and storing data.