<group />

A group is the basic container element that can contain other elements.

By default, a group doesn't have any effect on the circuit.

import { sel } from "tscircuit"

export default () => (
  <board width="10mm" height="10mm">
    <resistor name="R1" resistance="1k" schX={-2} />
    <group schY={-3}>
      <resistor name="R2" resistance="1k" schX={2} />
      <trace from={sel.R1.pin2} to={sel.R2.pin1} />
    </group>
  </board>
)

Props

Prop	Type	Description
name	string	Optional identifier for the group element.
children	any	Elements that will be rendered inside the group.
schTitle	string	Title displayed above the group in the schematic view.
showAsSchematicBox	boolean	When true, renders the group as a single schematic box.
connections	Connections	Map of external pin names to internal connection targets.
schPinArrangement	SchematicPinArrangement	Controls the ordering and sides of pins when shown as a schematic box.
schPinSpacing	Distance	Adjusts the spacing between schematic pins in box mode.
schPinStyle	SchematicPinStyle	Styles applied to individual pins in schematic box mode.
pcbWidth / pcbHeight	Distance	Override the PCB footprint width or height for the group box.
schWidth / schHeight	Distance	Override the schematic box width or height.
pcbLayout / schLayout	LayoutConfig	Advanced layout configuration objects applied to PCB or schematic views.
cellBorder / border	Border | null	Custom border styling for the group when rendered as a cell or schematic box.
schPadding*	Distance	Sets overall or per-side padding around schematic contents (schPadding, schPaddingLeft, etc.).
pcbPadding*	Distance	Sets overall or per-side padding around PCB contents (pcbPadding, pcbPaddingLeft, etc.).
pcbPositionAnchor	AutocompleteString<typeof ninePointAnchor>	Anchor used when interpreting pcbX/pcbY relative to pcbPosition.

Grid Layout Props

export default () => (
  <board width="26mm" height="20mm">
    <group pcbGrid pcbGridCols={2} pcbGridGap="1mm">
      <resistor name="R1" resistance="1k" footprint="0402" />
      <capacitor name="C1" capacitance="10uF" footprint="0402" />
      <led name="LED1" color="red" footprint="0603" />
      <chip name="U1" footprint="soic8" />
    </group>
  </board>
)

Prop	Type	Description
pcbGrid / schGrid	boolean	Enables CSS grid style layout in the PCB or schematic view.
pcbGridCols / schGridCols	number | string	Sets the number of columns in the grid.
pcbGridRows / schGridRows	number | string	Sets the number of rows in the grid.
pcbGridTemplateRows / schGridTemplateRows	string	Explicit template row sizes for the grid.
pcbGridTemplateColumns / schGridTemplateColumns	string	Explicit template column sizes for the grid.
pcbGridTemplate / schGridTemplate	string	Shorthand template definition covering both rows and columns.
pcbGridGap / schGridGap	number | string	Sets the row and column gap simultaneously.
pcbGridRowGap / schGridRowGap	number | string	Sets the gap between rows.
pcbGridColumnGap / schGridColumnGap	number | string	Sets the gap between columns.

Flex Layout Props

export default () => (
  <board width="26mm" height="20mm">
    <group pcbFlex pcbFlexGap="1mm" pcbAlignItems="center" pcbJustifyContent="space-between">
      <resistor name="R1" resistance="1k" footprint="0402" />
      <resistor name="R2" resistance="1k" footprint="0402" />
      <resistor name="R3" resistance="1k" footprint="0402" />
    </group>
  </board>
)

Prop	Type	Description
pcbFlex / schFlex	boolean | string	Enables flex layout for PCB or schematic contents; string values pass raw CSS flex settings.
pcbFlexGap / schFlexGap	number | string	Gap between items in a flex layout.
pcbFlexDirection / schFlexDirection	"row" | "column"	Controls primary axis direction.
pcbAlignItems / schAlignItems	"start" | "center" | "end" | "stretch"	Aligns items on the cross axis.
pcbJustifyContent / schJustifyContent	"start" | "center" | "end" | "stretch" | "space-between" | "space-around" | "space-evenly"	Aligns items on the main axis.
pcbFlexRow / schFlexRow	boolean	Convenience booleans for forcing row direction.
pcbFlexColumn / schFlexColumn	boolean	Convenience booleans for forcing column direction.
pcbGap / schGap	number | string	Legacy alias for flex gap sizing.
pcbPack / schPack	boolean	Enables flexbox packing utilities.
pcbPackGap	number | string	Gap used when pcbPack is enabled.
schMatchAdapt	boolean	In schematic flex layouts, match the adaptive flex sizing of PCB contents.

Showing a group as a schematic box

Use showAsSchematicBox to collapse a group into one schematic box with named pins. This is useful for modules and reusable blocks where the internal implementation should stay hidden in the schematic.

Only direct child <port /> elements are shown as box pins. Internal components and connectivity still exist for PCB and netlist generation, but their schematic symbols, traces, labels, and primitives are hidden inside the collapsed box.

export default () => (
  <board width="20mm" height="12mm" routingDisabled>
    <group name="FILTER" showAsSchematicBox schTitle="RC Filter">
      <port name="VIN" direction="left" />
      <port name="VOUT" direction="right" />
      <resistor name="R1" resistance="1k" footprint="0402" />
      <capacitor name="C1" capacitance="100nF" footprint="0402" />
    </group>
  </board>
)

External components can connect to a collapsed group with the group name and direct port name:

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

Creating ports from connections

For collapsed groups, each key in connections becomes an external box pin and each value points to the internal target. If a matching direct <port /> already exists, tscircuit uses it instead of creating a duplicate.

<group
  name="PULLUP"
  showAsSchematicBox
  connections={{
    IO: "R1.pin1",
    VCC: "R1.pin2",
  }}
>
  <resistor name="R1" resistance="10k" footprint="0402" />
</group>

schPinArrangement, schPinSpacing, schPinStyle, schWidth, and schHeight work on collapsed groups the same way they work on chip schematic boxes.

Example: LED matrix module

Collapsed schematic boxes are useful when a group contains repetitive internal circuits. This 3x3 LED matrix exposes row and column pins while hiding the individual LEDs in the schematic.

export default () => (
  <board width="34mm" height="22mm" routingDisabled>
    <group
      name="MATRIX"
      showAsSchematicBox
      schTitle="3x3 LED Matrix"
      schPinArrangement={{
        leftSide: {
          direction: "top-to-bottom",
          pins: ["ROW1", "ROW2", "ROW3"],
        },
        rightSide: {
          direction: "top-to-bottom",
          pins: ["COL1", "COL2", "COL3"],
        },
      }}
    >
      <port name="ROW1" />
      <port name="ROW2" />
      <port name="ROW3" />
      <port name="COL1" />
      <port name="COL2" />
      <port name="COL3" />

      <led
        name="D1"
        color="red"
        footprint="0603"
      />
      <led
        name="D2"
        color="red"
        footprint="0603"
      />
      <led
        name="D3"
        color="red"
        footprint="0603"
      />
      <led
        name="D4"
        color="red"
        footprint="0603"
      />
      <led
        name="D5"
        color="red"
        footprint="0603"
      />
      <led
        name="D6"
        color="red"
        footprint="0603"
      />
      <led
        name="D7"
        color="red"
        footprint="0603"
      />
      <led
        name="D8"
        color="red"
        footprint="0603"
      />
      <led
        name="D9"
        color="red"
        footprint="0603"
      />
    </group>
  </board>
)

Moving multiple components via a <group />

<group /> elements can be used to move multiple components at once.

In the example below every schematic symbol inside the <group /> will be moved 5mm to the right and 3mm up.

<group schX={5} schY={3}>
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" schY={2} />
  <resistor name="R3" resistance="1k" footprint="0402" schY={2} />
</group>

We can similarly use a <group /> to move multiple PCB elements at once:

<group pcbX={5} pcbY={3}>
  <resistor name="R1" resistance="1k" footprint="0402" />
  <resistor name="R2" resistance="1k" footprint="0402" pcbY={2} />
  <resistor name="R3" resistance="1k" footprint="0402" pcbY={2} />
</group>