> For the complete documentation index, see [llms.txt](https://help.qonic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.qonic.com/documentation/qonic-application/modelling/components-panel.md). # Components Panel Learn how to create and use components across your projects. A component is a reusable definition - a window, a door, a piece of furniture, an MEP terminal - that you create once and instance many times. The result is models that are faster to assemble and easier to keep coherent. ## Creating components To start creating your own components in the Qonic app, open the Components Panel on the right hand side, or use the shortcut Shift o. Here you will see a list of all component libraries in your current project if there are any. Click the ellipsis button next to a library to edit its name or delete it, or click the library name to open it and access the components inside.
Use the green + button at the bottom of this panel to create a new components library.
Once inside a library you can start saving components. Use the green + button at the bottom of this panel to create a new component, or select a product in your model, right-click it and choose *Create new component*. You will be prompted with a window to choose a Name, an IFC Class (this will be automatically filled in based on your selection) and optionally some tags and a description. You can still specify in which library to add this component. Select the object in your model you want to save as a component, and click Create. {% hint style="warning" %} You can only select a single product as the definition of your component. If you want to save a group of products as a component, create an [assembly](/documentation/qonic-application/modelling/modifying/assembly-editing.md) of these products first. {% endhint %}
The newly created component will now be listed in your library. If *Link selection to this component* is enabled, the product you selected for the creation of the component will automatically become an instance of this component. You can also create a component from a product in a model you can only view; that product then stays unlinked.
Related products around the selected product, such as the wall a window sits in, are copied into the component definition as [reference geometry](#reference-geometry). This reference geometry is not part of the component itself, and is never inserted along with it. Components can also be created through import of .rfa files. For more information about this, read [this article](/documentation/qonic-dashboard/components.md) about component management in the project dashboard. ## Placing components To place a component, simply drag and drop the component from the components panel into your model, or click the ellipsis next to the component name and choose *Insert*. If the component has more than one variant, you can choose which variant to insert. If your current selection can be replaced by the component, the menu offers *Insert & replace* instead, which replaces the selected products with the component.
The inserted component will follow the orientation of the object you used to create the component. When the component definition contains [reference geometry](#reference-geometry), enable *Smart snapping* while inserting to align the component automatically with the geometry you hover over. For example: * A window with a wall as reference geometry is automatically rotated and placed at the correct depth in any wall you hover over. * A wall-mounted toilet with a wall and a slab as reference geometry is automatically aligned and placed at the correct height when you move your cursor close to where a wall and a slab meet. Smart snapping is also available when moving or pasting products. ## Managing components An inserted component is effectively an instance of a component definition. The instance remains linked to the component definition. Whether a product is linked to a component definition (i.e. this product is a component instance) can be seen in the [Inspect panel](/documentation/qonic-application/data-and-collaboration/inspect-panel.md). An additional field will be displayed indicating the component it is referring to. Its menu offers the following actions: *Go to definition*, *Update*, *Replace with variant*, *Create new variant*, *Reset* and *Unlink*.
If a component **instance** was modified so that it deviates from the component **definition** (e.g. you edited its geometry or changed a property value), this will be automatically detected and indicated by this blue icon in the inspect panel.
When this is the case, you can choose to **reset** this component instance. The instance will again become an exact copy of the initial component definition, any changes made to this instance will be undone.
You can at any time **unlink** an instance from its definition. This will break the link, meaning that you will no longer be able to reset the instance or visit the component definition. If a component definition has been removed or edited, this will be indicated in the instance's properties in the inspect panel by a yellow triangle. When the instance is out of date, choose *Update* to update it to the latest version of the component.
In the desktop app, when your model uses an older version of one or more components, a banner is shown in the components panel. Click *Review Components* to open an overview of these components, where you can update instances, compare versions, ignore components you don't want to update, and show the instances in the model. From the components panel you have the options to insert a new component instance, find the component in your model, rename it, [open it for editing](#editing-components), show more information (such as tags, creator and last update), delete the component definition, and find all unlinked products. This last tool will scan your entire model for exact geometric matches of products with the component definition.
If any matches are found, they will be selected and you will have the option to convert these matches to component instances, essentially (re)linking the instances and the definition.
{% hint style="info" %} Creating, renaming and deleting component libraries and components happens in real time, and so does creating a component or a new variant from your model: other collaborators see these changes without you needing to publish anything. Changes you make while [editing a component](#editing-components), including new variants created there, are only visible to you until you publish them. {% endhint %} ## Component Variants Clicking a component name in the components panel will open the component details, listing the different variants of this component. Use variants to list e.g. doors with different sizes or furniture with different material variations. When creating a new component, it will by default only have one variant.
To create a new variant, go to one of the component instances, and make the desired modifications. As soon as you modify a component instance, this modification will be indicated in the Inspect Panel. You can also create and manage variants while [editing the component](#editing-components).
When a component instance is modified (i.e. it deviates from its definition), you will have the option to create a new variant from this. Select the modified instance and open up the right-click menu, or use *Create new variant* in the Inspect panel. This only works for a single product.
This will prompt you to enter a name and optionally more tags for this new variant.
Repeat this step for every variant you wish to make. Each variant will be listed under the component details. You can now insert any of these variants directly into your model, and set one of these new variants as the default for this component. The default variant is the one that will be inserted if you do not specify which variant to use.
If a component definition has more that one variant, you can swap out component instances with variations of its definition. Select the instances you want to replace, and in the right-click menu choose *Replace with variant*.
This opens the Replace tool, which allows you to pick from all available variants for this component, and replace your selection with this specific variant.
When picking your variant, a preview is shown of what the selected variant will look like. {% embed url="" %} ## Editing Components To change a component definition, open the component: in the components panel, click the ellipsis next to a component or variant and choose *Open*. You can also open a component from the [project dashboard](/documentation/qonic-dashboard/components.md). The component opens in a new tab, and the interface looks slightly different from a regular model, so you can tell you are editing a component: the top bar shows the component icon and name, and the background has a different color. To stop editing the component, close the tab. {% embed url="" %} To edit components, you need at least the status of **Editor** in this project. If someone else is already editing the component, you can only open it in read-only mode: the menu then shows *Open (Read Only)*. Some panels and tools are not available while you edit a component, such as the Report panel, the Quality Hub, the Issues panel, the Pinned panel, the spatial locations and types libraries, [grids](/documentation/qonic-application/modelling/creating/create-grid.md), and assigning a type, location or task to a product. ### Managing variants While editing a component, the [model picker](/documentation/qonic-application/basics/model-picker.md) lists the variants of the component instead of the models of your project. Click a variant to switch to it. * To create a new variant, click the **+** button in the model picker, and enter a name and optionally some tags. The new variant starts as a copy of the active variant. * Click the ellipsis next to a variant to *Rename*, *Duplicate* or *Delete* it, or to *Make Default*. The active variant and the default variant cannot be deleted. ### Reference geometry Reference geometry is geometry you define around the component in its definition, for example the wall a window sits in. It is kept as surrounding context to guide [smart snapping](#placing-components) when you insert the component, and is not part of the component itself. {% embed url="" %} To mark a product as reference geometry, right-click it while editing the component and choose *Set as reference*. Choose *Unset as reference* to make it a regular part of the component again. Currently walls, slabs and roofs are supported as reference geometry. ### Publishing changes Changes you make while editing a component are saved automatically, but other collaborators only see them once you publish them, in the same way as [model changes](/documentation/qonic-dashboard/models/model-version-management.md). If one of the variants is not valid, for example because it is empty, does not consist of a single product or has an invalid class, Qonic shows the *Invalid Component* dialog so you can review your changes first.