Skip to main content
Footprints

Footprint Elements vs Strings

Overview​

When setting the footprint property for a component in tscircuit, you can choose between two main approaches:

  1. Footprint Strings — Pass a concise string such as "0402", "soic8", "qfn32_w5mm_p0.5mm", "jlcpcb:C2040", or "kicad:Resistor_SMD/R_0402_1005Metric".
  2. Custom <footprint /> Elements — Compose a <footprint /> element from low-level PCB primitives such as <smtpad />, <platedhole />, and silkscreen elements.

Footprinter strings are quicker, more concise, and automatically attach a matching 3D CAD model for standard packages. Custom <footprint /> elements give you exact pad-by-pad, silkscreen, and fabrication-layer control for proprietary or non-standard parts.

To simplify an existing footprint with explicit pads into a compact footprinter string, use tsci convert --footprinter. Review the discovery report and verify geometry and electrical pin mapping before replacing it.

export default () => (
  <group>
    <resistor name="R1" footprint="0402" resistance="1k" pcbX={-3} />
    <resistor name="R2" footprint={
      <footprint>
        <smtpad portHints={["1"]} pcbX={-0.5} shape="rect" width={0.6} height={0.6} />
        <smtpad portHints={["2"]} pcbX={0.5} shape="rect" width={0.6} height={0.6} />
        <silkscreenpath route={[
          {x: -0.1, y: 0.2},
          {x: 0.1, y: 0.2}
        ]} />
        <silkscreenpath route={[
          {x: -0.1, y: -0.2}, 
          {x: 0.1, y: -0.2}
        ]} />
      </footprint>
    } pcbX={3} resistance="1k" />
  </group>
)
PCB Circuit Preview

Footprint String Sources​

Prefix / SyntaxExampleDescription
Footprinter Strings"0603", "soic8_w3.9mm", "qfn24_p0.5mm_thermalpad"Parametric package generator supporting passives, ICs, headers, transistors, and crystals
jlcpcb:"jlcpcb:C2040"Loads the verified PCB footprint and 3D model directly from JLCPCB / EasyEDA
kicad:"kicad:Package_SO/SOIC-8_3.9x4.9mm_P1.27mm"Loads an official KiCad .kicad_mod footprint by <Library>/<FootprintName>

Available <footprint /> Child Elements​

When building a custom <footprint />, you can combine any of the following copper, drill, silkscreen, fabrication, and constraint elements:

Copper & Drill Elements​

ElementDescription
<smtpad />Surface-mount copper pad (rect, circle, pill, or polygon) with portHints for electrical connection
<platedhole />Plated through-hole pad (circle, oval, pill, circular_hole_with_rect_pad, pill_hole_with_rect_pad, or hole_with_polygon_pad)
<hole />Non-plated mechanical drill hole or alignment boss cutout
<fiducial />Optical alignment mark for automated pick-and-place assembly

Silkscreen Elements​

ElementDescription
<silkscreentext />Silkscreen text label; supports {REF} / {NAME} placeholders for dynamic reference designators and isKnockout
<silkscreenrect />Rectangular silkscreen outline or filled marker block
<silkscreencircle />Circular silkscreen outline or filled Pin 1 indicator dot
<silkscreenline />Straight silkscreen line segment between (x1, y1) and (x2, y2)
<silkscreenpath />Multi-point polyline path drawn on the silkscreen layer
<silkscreengraphic />Custom SVG or PNG artwork (logos, icons, QR codes) rendered onto the silkscreen layer

Fabrication Note & Layout Constraint Elements​

ElementDescription
<fabricationnotetext />Text annotation on the PCB fabrication drawing layer for assembly instructions
<fabricationnoterect />Rectangular callout box or highlight region on the fabrication layer
<fabricationnotepath />Multi-point polyline or arrow drawn on the fabrication layer
<constraint />Declarative geometric constraint (centerToCenter, edgeToEdge, sameX, sameY) between pads and holes

Complete Custom Footprint Example​

The example below combines <smtpad />, <hole />, <silkscreenrect />, <silkscreencircle />, <silkscreentext />, and <fabricationnotetext /> inside a single reusable <footprint />:

export default () => (
  <board width="16mm" height="14mm">
    <chip
      name="U1"
      footprint={
        <footprint>
          <smtpad portHints={["1", "VCC"]} shape="rect" width="1.2mm" height="0.6mm" pcbX="-2.2mm" pcbY="0.65mm" />
          <smtpad portHints={["2", "GND"]} shape="rect" width="1.2mm" height="0.6mm" pcbX="-2.2mm" pcbY="-0.65mm" />
          <smtpad portHints={["3", "SDA"]} shape="rect" width="1.2mm" height="0.6mm" pcbX="2.2mm" pcbY="-0.65mm" />
          <smtpad portHints={["4", "SCL"]} shape="rect" width="1.2mm" height="0.6mm" pcbX="2.2mm" pcbY="0.65mm" />
          <silkscreenrect pcbX={0} pcbY={0} width="2.8mm" height="2.8mm" strokeWidth="0.15mm" />
          <silkscreencircle pcbX="-1.0mm" pcbY="1.0mm" radius="0.25mm" isFilled />
          <silkscreentext text="{REF}" pcbX={0} pcbY="2.4mm" fontSize="0.9mm" />
          <fabricationnotetext text="Pin 1 top-left" pcbX={0} pcbY="-2.6mm" fontSize="0.7mm" />
        </footprint>
      }
    />
  </board>
)
PCB Circuit Preview