Modeling Components let you define a set of geometry once, then place multiple instances of that definition across your project file. You create and manage component definitions in the Catalog section of the Project Browser, and place instances from the Explorer section. Edits made to the definition propagate to every instance automatically, while instance-level controls like position, datum assignment, and options stay local to each placement.
This article covers the following topics:
Creating Component Definitions
A Component Definition can be thought of like a reusable template that is defined once from model entities and stored within the Catalog. Component definitions can be used to create a variety of grouped entities – everything from single rooms to entire mutli-family units. Changes to component definitions, if referenced from a CDM, will be inherited anywhere the component is used.
There are two ways to create a new component definition:
Method 1: Navigate to the Catalogs tab and click + button next to Components to create a new component definition.
Method 2: Find the 'Create Component' command from the Command Palette.
You’ll be prompted to select the entities in 2D canvas to be included within the component definition.
Alternatively: you can start creating a component without any existing entities in your canvas, and create the contents of your component within Isolated Editing Mode (see Editing Modeling Components for more information on Isolated Editing Mode).
Confirm selection by clicking "Done" within the Prompt Bar.
You're now in Isolated Editing Mode where you can continue to edit component entities and name your component definition. When done editing, click the ‘Exit’ button in the Prompt Bar to leave Isolated Editing Mode and complete the definition setup process.
You'll be prompted to place a Component Instance, or copy of your newly defined component definition. Click 'Done' from the Prompt Bar to place the instance in the original location the entity was created.
The component instance is now ready to be used.
Placing Additional Component Instances
Component Instances are individual placements of a component definition that, like copies, retain the ability to inherit and persist changes across all instances when edited.
To place a component instance, navigate to the Explorer tab, and click the + plus button next to ‘Component Instances’ to search the Component Catalog. Select the desired component from the dropdown list. Place the selected component instance within the 2D canvas.
To place additional instances, either repeat the placement steps above, or select the instance in the 2D canvas and use the ‘Copy’ command to create and place additional instances.
Instance and Level Positioning Strategies
There are two ways to associate a component instance with vertical level positions, also referred to as datums: Replication and Remapping. Choosing the right method for each use case keeps geometry predictable when units move or change context.
Strategy 1 - Replication
Replication duplicates the Studio file's levels into the component definition as a unique copy. Internal level relationships stay fixed regardless of where the instance is placed. Use Replication for multi-level components, such as a townhome unit, where the relative position of levels within the component must stay consistent.
With a modeling component selected, in the Inspector, under ‘Placement’, check that the position type is set to ‘Replication’ (this is the default mode).
Assign a new ‘Origin-Relative Datum’ for the instance, which maps the lowest level inside the component to the assigned datum.
Set an offset if you need to override the vertical position while maintaining datum associations.
Strategy 2 - Remapping
Remapping lets the project's datums drive the component's vertical positioning. Use Remapping for components that need to fit varying floor heights, such as a single-story unit placed on floors of different heights. Remapping is limited to component definitions that have geometry on a single level.
With a modeling component selected, in the Inspector, under ‘Placement’, change the position type to ‘Remapping’.
Assign a specific level to the instance.
Confirm the instance positioning is now set to assigned to your intended level.
Editing Components - Isolated Editing Mode
Isolated Editing Mode lets you edit a component's geometry in isolation, with surrounding file content hidden, which reduces the risk of accidentally moving or altering surrounding geometry while editing component internals. Edits made inside Isolated Editing Mode update the original component definition stored within the Component Catalog and propagate to every instance placed within the canvas. Instance-level controls, like position and options, remain scoped to each individual placement and are not affected.
Note: Modeling components referenced in from another file are not directly editable and need to be edited in the Studio file where they were created.
Starting in either in the Explorer…
…or in the 2D canvas, select the modeling component instance you want to edit and right-click to open the context menu and select ‘Edit Component Definition’.
Make the required edits inside Isolated Editing Mode, which is indicated by the pink canvas border.
Click ‘Exit’ to leave Isolated Editing Mode.
Note: Edits made in Isolated Editing Mode are autosaving – meaning once you exit, any changes made are reflected in all component instances.
Verify the changes persist across all component instances.
Option Controls
Options on modeling components can work in two modes: Global – which applies the same value across all instances, or Per-Instance – which lets each component instance carry its own option value. Per-instance option values flow downstream into Config and Showroom, enabling each unit to be optioned independently. You do not need to duplicate component definitions to support both behaviors.
Creating a Global Option
Create a modeling component and place two component instances within the canvas.
Create an option, for example, a sink with casework and a pedestal vanity.
Enter Isolated Editing Mode by double-clicking, or right-clicking on an instance in the canvas and choosing ‘Edit Component Definition’. Then condition the desired geometry to the option.
Exit Isolated Editing Mode and toggle between option values to verify the option change persists across all instances.
Creating a Per-Instance Option
Follow the global option steps above to create and condition an option to entities within a component definition.
Navigate to the Components section within the Catalogs tab and select the component definition you want to add the per-instance option to.
With the component definition selected, navigate to the Inspector and click the + button next to ‘Add Entities’.
Navigate back to the Options tab and select the desired option to add it to the component definition and click ‘Done’ from the Prompt Bar.
Exit Isolated Editing Mode if no other component edits are desired.
Verify in the Active Options panel that changing instance-level options affects only selected component instances.
Note: These per-instance option values will report in Config and Showroom.
Exposed Instance Datums
Exposed Instance Datums (also called Ephemeral Datums) allow geometry outside a component — such as roofs — to reference levels that exist inside specific component instances. For example, when a component instance moves vertically, any geometry referencing its exposed instance datums, moves with it automatically.
Note: Exposed Instance Datums are currently available for a limited set of entity types, including roofs. Support for additional entity types is in development.
Roof Example: Assign a roof to the top-of-wall level of a second-floor unit component. If that unit moves vertically, the roof follows.
Place your modeling component instances using the ‘Replication’ position method.
Create a roof (or other supported entity).
In the Inspector, assign the roof to the replicated level and to the desired component instance.
Move the component instance vertically via 'Origin Relative Datum' settings.
Verify the roof follows component instance move.
Doc Referencing Modeling Components
Doc references let you pull component definitions from a source Central Data Model (CDM) file into another file, instead of recreating them manually. All dependencies — options, props, nested sub-components — transfer automatically with the reference. Updates made in the source CDM propagate to every project file that references the component. If a referenced component depends on an option or prop that already exists in the target file, the system resolves the conflict automatically.
To Doc Ref a Modeling Component
Open the target project file where you want to use the component.
Use the doc reference workflow to reference the component definition from your source CDM file.
In the Explorer, find the doc-referenced component(s) to add into your project file.
Place instances into the 2D Canvas.
Confirm that the component definition, including all dependencies (global or per-instance options, props, etc) have transferred successfully into the current project file.
