Mates
Mates in Onshape are different than mates in old CAD systems. Many assemblies require only one Onshape Mate between any two instances, as the movement (degrees of freedom) between those two instances is embedded in the Mate. Mates contain their own coordinate systems, so you can use one Mate to define the degrees of freedom between two entities. At the time of placing a mate between two entities, Onshape offers points on each entity to which to align with the mate's coordinate system. The suggested locations are based on the underlying geometry of the part and changing the geometry will change the location of the mate. This can be undesirable in certain situations, but you can also:
- Add an explicit Mate connector to an entity exactly where you want it if the geometry does not already allow an implicit Mate connector while creating a mate. For more information, see Mate Connector.
- Insert a layout or reference sketch in an Assembly to use for aligning Mate connectors.
- Use more than one mate if necessary.
Shortcut: m
Use the shortcut key j to hide/show mates in an assembly.
You can mate entities to the Origin in an Assembly. You can also Fix an entity in order to test the movement of assigned Mates using the context menu or drag.
Entities include: parts, assemblies, subassemblies, sketches, and surfaces.
In Onshape, mating has two aspects: Mate connectors and mates. Instead of mating instance geometry directly together, Onshape uses mate connectors. Mate connectors are local coordinate systems located on or between entities. They are used in a Mate feature to locate and orient instances with respect to each other. They are created explicitly outside the mate dialog or implicitly while creating a mate.
Start a new Mate feature. The Mate type is conveniently editable from within the dialog, allowing swift mate changes. Onshape defines mates based on the intended behavior of the instances. Each one restricts certain degrees of freedom, with Fastened restricting all six.
With an active Mate feature, hovering over faces and edges displays implicit mate connector points, representing potential locations to place a mate connector. These points appear in the centroid of a face or sketch profile, midpoints, vertices, centers of circular openings, centers of negative space for cuts, and virtual sharps of conic faces.
Hold Shift to keep the current reference face or edge locked when moving the cursor. This makes selecting a point easier when it is located in a tight area or negative space. As the cursor moves over geometry, the mate connector snaps to the closest point.
In this example, the first selection is a mate connector point at the center of a hole. This face should touch and align with a circular face on the other instance. Circular faces and edges are the fastest way to select a mate connector point because they do not have midpoints or vertices; they only have a centroid. The second selection for this mate is the circular edge on the second instance, where it should touch and align with the first. The instances move together and are positioned with the mate connectors' primary Z axis aligned.
Click the arrow icon to flip the direction of the primary axis. Click the Reorient secondary axis icon to rotate the secondary axis in 90-degree increments. The field's top mate connector indicates what is flipped or rotated. If its movement is constrained, the field's bottom mate connector flips or rotates instead. To reorient the other mate connector, click Reorder items and then use the handles on the right side to rearrange. Click Done to finalize the reorder. Now, when reorienting the secondary axis, the other mate connector is rotating.
Each mate feature defines the degrees of freedom between the mate connectors. Visualize the mate's movement with the Animate mate degree of freedom icon. A fastened mate has zero degrees of freedom, so there is no movement between the mate connectors. If the mate type is changed to a Slider, animating moves the instance along the primary Z axis.
Mate features support offsetting and applying limits. Use Offset to move or rotate an instance along an axis with a set value. Use Limits to restrict a mate's range of motion. Available limits are based on the mate's degrees of freedom.
While a Mate feature is being defined, Onshape does not continually calculate all mates and their positions until the Mate feature is accepted. Use Solve to calculate all mate features and update instance positions.
Under Mate Features, defined mates are listed chronologically. Mates with limits display a limit icon. Hover the cursor over a mate to see the mate's offset and limit definitions. Right-click a mate for its context menu. Edit the mate from the context menu or double-click the mate to edit it. Apply limit positions to see the full range of motions based on defined limits. Reset the mate back to its original position. Delete removes it from the assembly.
Mates are defined through the Mate dialog:
You select the type of mate to create, then select the Mate connectors (one for each part). You are also able to check the box to apply limits of movement. Other options/action include:
-
- Flip the primary axis, Z orientation, of the instances.
-
- Reorient the secondary axis; rotate the quadrant orientation (in the XY plane) of the instances by 90 degrees at a click.
-
- Preview the animation of unlimited movement of the mate, ignoring all other mates in the assembly.
- Solve - Solve all assembly mates including this one.
Many mates offer the ability to set an Offset distance for defining a fixed space between the parts being mated, as well as distance Limits for movement.
Limits are visualized in the graphics area as dashed lines with bars at the ends. The dashed lines represent the direction and distance of the movement and the solid lines represent the limit.
If a Mate has one or more applied limits, the Mate limit indicator icon
is visible to the right of the Mate in the Mate Features list.
Offset distances are visualized in the graphics area as dashed lines between the Mates, displaying the value and the axis. Enter the distance in the dialog.
When you click on a Mate, graphics are displayed to indicate the direction of the X, Y, and, Z as defined by the Mate along the with the offset and the range of limits dimensions (if any).
Applying an offset should be viewed as moving the entire coordinate system. The offset is relative to the Mate connector selected first.
When the Offset box is checked, many mates also offer an option to specify rotation about a specific axis: Slider, Revolute, Pin Slot, Planar, and Fastened mates include the option, as see below:
Select the axis about which to rotate, above, then enter the degrees of rotation
When you open a Mate dialog and select two Mate connectors, a head-up display appears at your cursor:
Click the checkmark in the head-up display to commit the current mate and start a new Mate. The Mate dialog box stays open, and you are free to continue selecting Mates.
Offset distances are visualized in the graphics area as dashed lines between the Mates, with editable values. Drag the part to a desired position, double-click the distance value and enter a new value. These values are not persisted; you can use them to estimate values to enter in the Offset field in the dialog, or place parts in precise positions in order to take measurements. For example:
Mate values for axes and rotational movement (above).
Mate value in edit (above).
Use the Mate context menu to access the following commands:
- Rename - Specify a different name for the Mate
- Edit... - Change the Mate definition (even if the Mate is suppressed)
- Apply limit position - When a limit is created for a Mate, automatically move the instance to the minimum or maximum limit value.
- Reset - After an assembly is dragged to test movement of Mates, use Reset to return the assembly to its starting/home position (assuming constraints don't restrict that)
- Animate - Drive the assembly from a single Mate (or single DOF within a mate)
- Hide - Remove from view (Show displays the Mate again)
- Show all mates - Show all Mate connectors
- Isolate - Dim and inactivate all other parts except those selected (or associated with a selected Mate). When in Isolate mode, Exit isolate appears at the top of this menu. For more information, see Managing Assemblies.
- Make transparent - Dim parts nearest to the mate selected. Use the slider on the Make transparent dialog to extend the transparency out to other parts either by distance from, or by connectivity to, the selected mate.
- Suppress - Visualize the assembly without the Mate (and without deleting the Mate); Mates and Mate connectors are automatically made inactive when the part or assembly they are associated with are suppressed. (Suppressed Mates are still editable.)
- Clear selection - Clear all selections
- Delete - Remove the Mate from the assembly
Once a Mate is created between two explicit or implicit Mate connectors, you can edit either Mate connector:
-
Open the Mate dialog. In the example below, the Fastened mate is used as an example. The process is similar for all Mates, except Tangent mate which does not use Mate connectors.
-
Click the Mate connector icon (
). The Mate connector dialog opens, where you can edit the mate connector's origin type, origin entity, alignment, location, primary axis direction, and secondary axis orientation:
Editing Mate connectors from the Mate dialog is limited to implicit or explicit connectors located in the current Assembly. Mate connectors from Part Studios, subassemblies, or linked documents must be edited in their original location.
See Mate connector for more information.
Once a Mate is created and listed in the Mate Features list, select a Mate (or Ctrl+click to select more than one) and drag/drop to reorder them in the list. This will help put the most important mate features higher and more visible in the list. Onshape solves mates simultaneously so order won't affect a Mate.
You can specify Mate values of all mates except Ball, Fastened, Tangent, and Width. Onshape provides visual cues for distances, and provides distance values, in default units, from the second Mate connector selected to the first. Specify limits in positive and negative values.
In this example, the Mate connector on the box was the first one selected in the dialog; the Mate connector on the cylinder was the second selected. Notice that the Y value is negative and the X value is positive.
Now, switch the order of Mate connector selection and notice the distance values:
Notice that in this scenario, the Y value is positive and the X value is positive. This is due to the order of measurement from one Mate connector to the other. It's important to remember that the measurement is made from the second selected Mate connector to the first, along the coordinate system.
Use these distance visualizations to estimate the value to enter in the Limits box:
- When the Limits check box is present for a Mate, click to enable degrees of freedom fields to enter values for the minimum and maximum distances, as measured from the second Mate connector selected, to the first selected.
- Using the distance visualization as a guide (drag the part to activate), enter a minimum and maximum value.
- Use the Play button to animate the movement, including limits.
You can use expressions and trigonometric functions in numeric fields in Assemblies.
Onshape provides visual indicators to determine what instances have degrees of freedom or motion that remain unconstrained.
If an instance can move within any of its degrees of freedom, a triad icon is found next to the Instance in the list. Hovering over this icon reveals the tooltip indicating it has degrees of freedom. Toggle subassembly rigidity with the lock icon in the list, or right-click the subassembly and select Lock/follow position to. Choose between locking it to the current position and having it follow a Named position.
A subassembly in which all components are fully constrained displays a Rigid icon instead of the standard assembly icon.
The top-level assembly icon denotes how the assembly is constrained in space: It can either be fixed, which locks an instance in its current position and location, or fastened with a mate to the origin. Neither of these carries over when the assembly is inserted into another assembly. Only one foundational component should be defined this way.
There are several ways to observe the assembly's motion. The easiest method is to simply click and drag on the assembly's movable instances. The movement is dependent on the defined mate features. For example, a slider mate restricts the degrees of freedom between this Piston subassembly and the Barrel, allowing for only one linear degree of freedom. This mate has a limit established, which means it can only drag so far before it stops.
The triad manipulator provides a precision drag, allowing specific values to define the movement.
Mates with degrees of freedom have the option to animate. Right-click the mate in the list and select Animate. Mates with more than one degree of freedom prompt for a selection. If a limit is applied to the mate, the Start and End value distances are automatically set to the full range of that limit by default. Enter values to designate the range of motion. Steps define the speed of the animation. A lower value produces a faster animation, and a higher value produces a slower one. Under the Playback type, select Single to play the animation once, Reciprocate to play it continuously from the start value to the end value and back until manually stopped, or Loop to play it continuously from the start to end until manually stopped. Click the arrow icon to reverse the animation. The current value is a read-only field populated during the animation as the Mate moves.
Click the Play icon to view the animation and click the Stop icon to halt it.
Use the Animate command (found in the context menu for mates and mate indicators) to drive the assembly from a single Mate (or single DOF within a Mate). Other Mates and relations in the assembly are also enforced and honored.
If you have defined limits for the Mate, those values are used as the start and stop points during the animation.
- Right-click on a mate or mate indicator and select Animate.

- Animate works with only one degree of freedom at a time, so if the Mate has more than one, you are prompted to select one.
- Enter Start and End values. If Limits are specified in the Mate definition, those values are automatically populated in the Start value and End value fields. If no Limits are specified in the Mate dialog, enter values now.
- Start value - The minimum distance measured along the degree of freedom’s axis. (By default, the value as specified in the Mate Minimum Limit.)
- End value - The maximum distance measured along the degree of freedom’s axis. (By default, the value as specified in the Mate Maximum Limit.)
You can enter up to 36000 degrees here (100 revolutions), specifically helpful for visualizing degrees of freedom in high-ratio gears and rack and pinion relations.
- Specify Steps, a linear map from the start to end value, inclusive, interpolated at each step. The minimum number of steps is 2. By default, playback is around 60 steps/second.
- Select a playback type, Single or Reciprocate to play the animation of the degrees of freedom once or continuously until you manually stop it, respectively.
Current value is a read-only field and is populated during animation as the Mate moves through the degrees of freedom, in your specified units. When the motion stops (either automatically or manually), Current value displays the point at which the motion was stopped.
Animate supports all Mate types but it’s not recommended to use Fastened, Tangent, or Ball as the driving mate.
Tips
- The Animate command works with various graphics modes, like Isolate, Mate indicators and Mate connectors.
- Animate helps you explore the relationships between Mates, their constraint systems, and gives you a way to show off your design (especially with the playback loop feature, specifically for rotational degrees of freedom).
Offsetting entities from one another during assembly is available for the following Mate types:
- Planar offset - Along the Z axis
- Slider offset - Along the X and Y axes
- Revolute offset - Along the Z axis
- Pin slot offset - Along the Z axis
- Fastened offset - Along the X, Y, and, Z axes
You can also drag the entities and observe the distance values in the graphics area. These will help determine the specific values to enter in the dialog.
You can use expressions and trigonometric functions in numeric fields in Assemblies.
You can copy and paste entities that have been mated in an Assembly:
- Select the entities.
- From the context menu, select Copy items:
- From the context-menu, paste the items:
The entities are pasted directly where the mouse click occurs.
Notice that the entities, Mate connectors, and mates are also duplicated in the Assembly list.
In addition to being visible in the Assembly list, mates have indicators in the graphics area as well. You can hide the entities and Mate connectors in the Assembly list in order to see these mate indicators more clearly. These indicators give hints at the type of motion they define as well as the current state: blue/white indicates good Mates, gray indicates suppressed or inactive, and red indicates a problem. (Suppressed Mates are still editable.)
Fastened
Revolute
Slider
Planar
Cylindrical
Pin slot, with an arrow in the direction of the slot
Ball
Parallel
Tangent
Width
Group
More tips for visualizing Mates:
- Select a part, right-click for the context menu and select Show mates.
- Hover over a Mate, right-click for the context menu where you can take action on the Mate.
- Select a Mate, Mate connector, or Mate relation in the graphics area and its associated instances and Mate feature are highlighted in the list.
- There is exactly one Mate between any two instances.
- Fixing an entity is different from applying a Mate. Fix (found in the context menu) is specific to the assembly in which it is applied; it does not carry over to any other assembly that entity is inserted into.
- The Mate positions two instances in relationship to each other, aligning a Mate connector on each instance.
Before Mate

After Mate

- The initial position is often a best guess. There are two tools to correct the position:
- The Flip primary axis tool flips the major (Z) orientation.


- The Reorient secondary axis tool adjusts the orientation in 90 degree increments
-
The play button
animates the allowed movement between the Mate being created.
- The Solve button regenerates the mate in process and the movement of all Mates, so you have the ability to see how your changes affect the entire assembly.
The Mate type then specifies the degrees of freedom behavior.
- Select a Mate (for example
) to open the dialog:

- Select one automatic Mate connector on each entity (you can also Mate to the Origin):
- If necessary, adjust the orientation using Flip Primary Axis or Rotate Secondary Axes.
- Accept the Mate
.

In the example above, only automatic Mate connectors were used. In most mating cases, automatic Mate connectors will work fine. In some less common cases, it may be useful to create Mate connectors ahead of time. You can create Mate connectors in either the Assembly or in the Part Studio.
Mates in Onshape are different than mates in traditional CAD systems. You may need only one Onshape Mate between any two instances, as the movement (degrees of freedom) between those two instances is embedded in the Mate.
You can mate an entity to the Origin in an Assembly. You can also Fix an entity, in order to test the movement of assigned Mates, using the context menu. Entities include: parts, assemblies, subassemblies, sketches, and surfaces.
Mates are defined through the Mate dialog:
Select the type of Mate to create, then select the Mate connectors (one for each part).
Mate type - The Mate type field displays the type of Mate you are using. Tap to open a list of Mate types and tap to select one.
Mate connectors - The next section, Mate connectors, is highlighted in blue. This indicates that a selection from the graphics area is required. Two Mate connectors (one from each instance being mated) must be selected.
Offset - Tap to set an offset distance for defining a fixed space between the parts being mated.
Limits - Tap to set distance limits for movement.
- Flip the primary axis, Z orientation of the instances.
- Reorient the secondary axis; rotate the quadrant orientation (in the XY plane) of the instances by 90 degrees at a tap.
Solve - Tap to solve all assembly Mates including the current one.
You can specify movement limits of all Mates except Ball, Fastened, and Tangent.
Inside the dialog of a Mate that allows limits (Revolute, Slider, Planar, Cylindrical, and Pin slot) toggle the Limits button on and limit fields appear.
Enter desired limit specifications and tap Solve to visualize the changes.
Offsetting entities from one another during assembly is available for the following Mate types:
- Planar offset - Along the Z axis
- Slider offset - Along the X and Y axes
- Revolute offset - Along the Z axis
- Pin slot offset - Along the Z axis
- Fastened offset - Along the X, Y, and, Z axes
You can also drag the entities and observe the distance values in the graphics area. These will help determine the specific values to enter in the dialog.
You can also use expressions and trigonometric functions in numeric fields in Assemblies.
In addition to being visible in the Assembly list, Mates have indicators in the graphics area as well. You can hide the entities and Mate connectors in the Assembly list in order to see these Mate indicators more clearly. These indicators give hints at the type of motion they define as well as the current state: blue/white indicates good Mates, gray indicates suppressed or inactive, and red indicates a problem. Note that Mates and Mate connectors are suppressed when the part or assembly they are associated with is suppressed. (Suppressed Mates are still editable.)
Fastened
Revolute
Slider
Planar
Cylindrical
Pin slot, with an arrow in the direction of the slot
Ball
Tangent
Parallel
Group
More tips for visualizing Mates:
- Two-finger tap for the context menu, tap Show all to show everything listed in the Instance list, including Mate connectors and Mate indicators. Use Hide all or Hide other mates as well.
- Tap on a Mate in the Instance list.
- There is exactly one Mate between any two instances.
- Fixing an entity is different from applying a Mate. Fix (found in the context menu) is specific to the assembly in which it is applied; it does not carry over to any other assembly that entity is inserted into.
- The Mate positions two part instances in relationship to each other, aligning a Mate connector on each instance.
Before Mate

After Mate

- The initial position is often a best guess. There are two tools to correct the position:
The
Flip primary axis
tool flips the major (Z) orientation.
The
Reorient secondary axis
tool adjusts the orientation in 90 degree increments.
- The Solve button regenerates the mate in process and the movement of all Mates, so you have the ability to see how your changes affect the entire assembly.
The Mate type specifies the movement behavior.
Mates in Onshape are different than mates in traditional CAD systems. You may need only one Onshape Mate between any two instances, as the movement (degrees of freedom) between those two instances is embedded in the Mate.
You can mate an entity to the Origin in an Assembly. You can also Fix an entity, in order to test the movement of assigned Mates, using the context menu. Entities include: parts, assemblies, subassemblies, sketches, and surfaces.
Mates are defined through the Mate dialog:
Select the type of Mate to create, then select the Mate connectors, implicit or explicit (one for each part).
Mate type - The Mate type field displays the type of Mate you are using. Tap to open a list of Mate types and tap to select one.
Mate connectors - The next section, Mate connectors, is highlighted in blue. This indicates that a selection from the graphics area is required. Two Mate connectors (one from each instance being mated) must be selected.
Offset - Tap to set an offset distance for defining a fixed space between the parts being mated.
Limits - Tap to set distance limits for movement.
- Flip the primary axis, Z orientation of the instances.
- Reorient the secondary axis; rotate the quadrant orientation (in the XY plane) of the instances by 90 degrees at a tap.
Solve - Tap to solve all assembly Mates including the current one.
You can specify movement limits of all Mates except Ball, Fastened, and Tangent.
Inside the dialog of a Mate that allows limits (Revolute, Slider, Planar, Cylindrical, and Pin slot) toggle the Limits button on and limit fields appear.
Enter desired limit specifications and tap Solve to visualize the changes.
Offsetting entities from one another during assembly is available for the following Mate types:
- Planar offset - Along the Z axis
- Slider offset - Along the X and Y axes
- Revolute offset - Along the Z axis
- Pin slot offset - Along the Z axis
- Fastened offset - Along the X, Y, and, Z axes
You can also drag the entities and observe the distance values in the graphics area. These will help determine the specific values to enter in the dialog.
You can use expressions and trigonometric functions in numeric fields in Assemblies.
In addition to being visible in the Assembly list, Mates have indicators in the graphics area as well. You can hide the entities and Mate connectors in the Assembly list in order to see these Mate indicators more clearly. These indicators give hints at the type of motion they define as well as the current state: blue/white indicates good Mates, gray indicates suppressed or inactive, and red indicates a problem. (Suppressed Mates are still editable.)
Fastened
Revolute
Slider
Planar
Cylindrical
Pin slot, with an arrow in the direction of the slot
Ball
Tangent
Parallel
Group
More tips for visualizing Mates:
- Two-finger tap for the context menu, tap Show all to show everything listed in the Instance list, including Mate connectors and Mate indicators.
- Tap on a Mate in the Instance list.
- There is exactly one Mate between any two instances.
- Fixing an entity is different from applying a Mate. Fix (found in the context menu) is specific to the assembly in which it is applied; it does not carry over to any other assembly that entity is inserted into.
- The Mate positions two part instances in relationship to each other, aligning a Mate connector on each instance.
Before Mate

After Mate

- The initial position is often a best guess. There are two tools to correct the position:
The
Flip primary axis
tool flips the major (Z) orientation.
The
Reorient secondary axis
tool adjusts the orientation in 90 degree increments.
- The Solve button regenerates the Mate in process and the movement of all Mates, so you have the ability to see how your changes affect the entire assembly.
The Mate type specifies the movement behavior.
For additional Learning center resources, follow the technical briefing articles here: Mating Basics (Onshape account required) and Advanced Mating Techniques (Onshape account required).

