Skip to main content
Built-in Elements

<subcircuit />

Overview​

A <subcircuit /> is a powerful organizational element in tscircuit that represents a collection of elements that are tightly coupled. Subcircuits are often used for a small functional block, such as a voltage regulator.

Within a subcircuit, you can have a custom autorouter or isolated nets from the larger circuits. You can also re-use reference designators. Your subcircuit is essentially isolated from other subcircuits.

export default () => (
  <board width="10mm" height="10mm">
    <subcircuit name="subcircuit1" schX={-2}>
      <resistor name="R1" resistance="1k" footprint="0402" />
    </subcircuit>
    <subcircuit name="subcircuit2" schX={2}>
      <resistor name="R2" resistance="1k" footprint="0402"  />
    </subcircuit>
    <trace from=".subcircuit1 .R1 .pin1" to=".subcircuit2 .R2 .pin1" />
  </board>
)
Schematic Circuit Preview

Exposing Ports​

Subcircuit selectors are isolated by default. To give the parent circuit a stable connection point without exposing an internal reference designator, add a direct child <port /> with connectsTo:

<subcircuit name="FILTER" showAsSchematicBox>
  <resistor name="R1" resistance="1k" footprint="0402" />
  <port name="INPUT" direction="left" connectsTo="R1.pin1" />
  <port name="OUTPUT" direction="right" connectsTo="R1.pin2" />
</subcircuit>

<resistor
  name="R_LOAD"
  resistance="10k"
  footprint="0402"
  connections={{ pin1: "FILTER.OUTPUT", pin2: "net.GND" }}
/>

connectsTo is resolved inside the subcircuit, while FILTER.OUTPUT is resolved by the parent circuit against the public port. You can therefore rename or reorganize internal components without changing connections outside the subcircuit.

When showAsSchematicBox is enabled, direct child ports are displayed as the box pins. Without it, the ports still define the public electrical interface. See the port documentation for a complete example and explicit trace selector syntax.

Reuse Reference Designators​

Reusing reference designators is typically considered a bad practice, but in tscircuit reference designators are intelligently prefixed prior to being written on the silkscreen. This means that you can design your subcircuits without worrying about whether or not a reference designator has been previously used.

Within a subcircuit, you'll never select inside of another subcircuit without explicitly specifying the subcircuit name in a selector. This means you never need to worry about other R1 or C1 selectors from other subcircuits, they will not be selected unless you explicitly include a subcircuit selector e.g. .somesubcircuit .R1

export default () => (
  <board width="10mm" height="10mm">
    <subcircuit name="subcircuit1" schX={-2}>
      <resistor name="R1" resistance="1k" footprint="0402" />
    </subcircuit>
    <subcircuit name="subcircuit2" schX={2}>
      <resistor name="R1" resistance="1k" footprint="0402" />
    </subcircuit>
    <trace from=".subcircuit1 .R1 .pin1" to=".subcircuit2 .R1 .pin1" />
  </board>
)
Schematic Circuit Preview

Configuring the Autorouter​

Subcircuits can have a custom autorouter configuration. This will be inherited by any children subcircuits.

To specify a custom autorouter configuration, just set the autorouter property on a <subcircuit /> element.

<subcircuit autorouter="auto-cloud">
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" />
  {/* ... */}
</subcircuit>

Specifying custom autorouter settings for subcircuits can be extremely useful when you have a tricky section of components that have special requirements.

Read more about the autorouter prop here.