<assembly.subassembly />

assembly.subassembly groups mechanical parts in one local frame. It can have its own CAD model, children, or both. A group with no geometry can still define mounting faces and move all its children together. assembly.cadassembly is an alias with the same props.

Mount a group with relative offsets

The base's mount face is at Z = 6 mm. MODULE mates its base to that face, moves 6 mm along the face's X tangent and −4 mm along its Y tangent, and leaves a 2 mm inspection gap. The blue housing and steel bearing inherit the group frame.

import { assembly } from "tscircuit"
import { BearingHousing, SlottedBase, bearingModel } from "./models"

export default () => (
  <assembly.device>
    <assembly.printedpart name="BASE" jscad={<SlottedBase />}>
      <assembly.referencesurface name="mount" centerZOffset={6} />
    </assembly.printedpart>
    <assembly.subassembly name="MODULE"
      mountedTo=".BASE > .mount" mountFace="base"
      mountOffset={{ x: "6mm", y: "-4mm" }} mountGap="2mm">
      <assembly.referencesurface name="base" normalDirection="z-" />
    <assembly.printedpart name="HOUSING" jscad={<BearingHousing />}>
      <assembly.referencesurface name="bearingSeat" centerZOffset={4} />
      <assembly.referencesurface name="boltSeat"
        centerXOffset={22} centerYOffset={12} centerZOffset={6} />
    </assembly.printedpart>
    <assembly.part name="BEARING"
      cadModel={bearingModel}
      mountedTo=".HOUSING > .bearingSeat" mountFace="base">
      <assembly.referencesurface name="base" normalDirection="z-" />
    </assembly.part>
    </assembly.subassembly>
  </assembly.device>
)

MODULE has no model of its own. Its origin resolves to [6, -4, 8] mm. The bearing's bottom is another 4 mm above that origin, at its housing's pocket floor. Change the outer mount to reposition the complete module; the child parts' internal face constraints stay the same.

Offsets use the target face's local axes. Rotating a target frame changes the directions followed by mountOffset.x/y; mountGap always follows its outward normal. See assembly.referencesurface for XY, XZ and YZ frame directions.

Subassembly properties

Property	Description
name	Required group name.
displayName	Optional display label.
purchaseUrls	Optional array of HTTP(S) purchase links for this subassembly.
supplierPartNumbers	Optional supplier-to-SKU map for this subassembly.
model	Modelprinter string or HTTP(S) model URL.
modelUrl	Imported CAD model URL.
cadModel	Model with advanced alignment options; see cadmodel.
mountedTo	Target reference face selector, such as .BASE > .mount. Compact paths such as BASE.mount also work.
mountFace	Named reference face on this group; supply with mountedTo.
mountOffset	Optional signed target-local { x?, y? } distances. Omitted axes are zero. Requires mountedTo.
mountGap	Optional nonnegative normal clearance, default zero. Requires mountedTo.
children	Reference surfaces, nested assembly elements, or CAD models.

Choose at most one of model, modelUrl, or cadModel. Omit all three for a group with no model. Reference surfaces can be children of either kind of group.

Bill of materials

Each subassembly emits one assembly BOM material line, including a subassembly with no model. Nested assembly materials appear beneath their nearest material ancestor. displayName supplies the label when present; otherwise name is used. Moving the group with mountedTo does not change BOM ownership.

Purchase links and supplier SKUs belong to the subassembly's own line. Its children remain separate materials; nesting does not mean their cost is included in the parent. See the assembly BOM example for purchasing props, repeated parts and converting Circuit JSON to a nested BOM.

Group placement and model alignment

A mount determines the group's full rigid frame, including tilt, and its children inherit that frame. Unmounted groups inherit their containing assembly's placement; a standalone unmounted group starts at the world origin. References resolve within the nearest assembly.device; qualify selectors when several groups contain parts with the same name.

cadModel.positionOffset and rotationOffset affect only the group's own mesh. Use them to align an imported asset's origin to its authored reference surfaces. Use a face mount to position the group and its children together.

For fasteners that follow actual PCB holes or mechanical hole datums, use assembly.bolt. For a connector-relative display, use assembly.screen.