KiCad Metadata

tscircuit components support KiCad-specific metadata properties that preserve information from KiCad footprint and symbol files. These properties are available on all normal components (chip, resistor, capacitor, etc.) and are useful when importing from KiCad or when you need to include KiCad-specific information in your exported designs.

Properties Overview

Property	Element	Description
`kicadFootprintMetadata`	Components	Metadata from KiCad footprint (`.kicad_mod`) files
`kicadSymbolMetadata`	Components	Metadata from KiCad symbol (`.kicad_sym`) files
`kicadPinMetadata`	`<port />`	Metadata for KiCad pin electrical and visual properties

kicadFootprintMetadata

The kicadFootprintMetadata property stores metadata extracted from KiCad footprint files. This includes information about the footprint's properties, attributes, pads, and 3D model.

Type Definition

interface KicadFootprintMetadata {
  footprintName?: string
  version?: number | string
  generator?: string
  generatorVersion?: number | string
  layer?: string
  properties?: KicadFootprintProperties
  attributes?: KicadFootprintAttributes
  pads?: KicadFootprintPad[]
  embeddedFonts?: boolean
  model?: KicadFootprintModel
}

Properties

Top-level Properties

Property	Type	Description
`footprintName`	`string`	Name identifier for the footprint
`version`	`number \| string`	KiCad file format version
`generator`	`string`	Tool that generated the footprint
`generatorVersion`	`number \| string`	Version of the generator tool
`layer`	`string`	Default layer (e.g., `"F.Cu"`)
`embeddedFonts`	`boolean`	Whether fonts are embedded in the footprint

properties

Standard KiCad footprint properties for documentation:

interface KicadFootprintProperties {
  Reference?: KicadProperty   // Component reference designator (e.g., "R1")
  Value?: KicadProperty       // Component value (e.g., "10k")
  Datasheet?: KicadProperty   // Link to component datasheet
  Description?: KicadProperty // Human-readable description
}

interface KicadProperty {
  value: string
  at?: { x: number | string; y: number | string; rotation?: number | string }
  layer?: string
  uuid?: string
  hide?: boolean
  effects?: {
    font?: {
      size?: { x: number | string; y: number | string }
      thickness?: number | string
    }
  }
}

attributes

Footprint manufacturing attributes:

interface KicadFootprintAttributes {
  through_hole?: boolean          // THT component
  smd?: boolean                   // SMD component
  exclude_from_pos_files?: boolean // Exclude from pick-and-place
  exclude_from_bom?: boolean       // Exclude from bill of materials
}

pads

Array of pad definitions:

interface KicadFootprintPad {
  name: string                    // Pad name/number
  type: string                    // Pad type (e.g., "smd", "thru_hole")
  shape?: string                  // Pad shape (e.g., "rect", "circle", "oval")
  at?: { x: number | string; y: number | string; rotation?: number | string }
  size?: { x: number | string; y: number | string }
  drill?: number | string         // Drill diameter for THT pads
  layers?: string[]               // Copper layers (e.g., ["F.Cu", "F.Paste"])
  removeUnusedLayers?: boolean
  uuid?: string
}

model

3D model reference and transforms:

interface KicadFootprintModel {
  path: string                    // Path to 3D model file
  offset?: { x: number | string; y: number | string; z: number | string }
  scale?: { x: number | string; y: number | string; z: number | string }
  rotate?: { x: number | string; y: number | string; z: number | string }
}

Example Usage

<chip
  name="U1"
  footprint="soic8"
  kicadFootprintMetadata={{
    footprintName: "SOIC-8_3.9x4.9mm_P1.27mm",
    generator: "kicad-component-converter",
    layer: "F.Cu",
    properties: {
      Reference: { value: "U", hide: false },
      Value: { value: "SOIC-8", hide: false },
      Datasheet: { value: "", hide: true },
      Description: { value: "8-pin SOIC package" }
    },
    attributes: {
      smd: true,
      exclude_from_bom: false
    },
    model: {
      path: "${KICAD8_3DMODEL_DIR}/Package_SO.3dshapes/SOIC-8_3.9x4.9mm_P1.27mm.wrl",
      offset: { x: 0, y: 0, z: 0 },
      scale: { x: 1, y: 1, z: 1 },
      rotate: { x: 0, y: 0, z: 0 }
    }
  }}
/>

kicadSymbolMetadata

The kicadSymbolMetadata property stores metadata extracted from KiCad symbol files. This includes schematic-specific information like pin configuration, BOM settings, and symbol properties.

Type Definition

interface KicadSymbolMetadata {
  symbolName?: string
  extends?: string
  pinNumbers?: KicadSymbolPinNumbers
  pinNames?: KicadSymbolPinNames
  excludeFromSim?: boolean
  inBom?: boolean
  onBoard?: boolean
  properties?: KicadSymbolProperties
  embeddedFonts?: boolean
}

Properties

Top-level Properties

Property	Type	Description
`symbolName`	`string`	Symbol identifier name
`extends`	`string`	Parent symbol for inheritance
`excludeFromSim`	`boolean`	Exclude from SPICE simulation
`inBom`	`boolean`	Include in bill of materials
`onBoard`	`boolean`	Component appears on PCB
`embeddedFonts`	`boolean`	Whether fonts are embedded

pinNumbers

Pin number display configuration:

interface KicadSymbolPinNumbers {
  hide?: boolean  // Hide pin numbers in schematic
}

pinNames

Pin name display configuration:

interface KicadSymbolPinNames {
  offset?: number | string  // Distance from pin to name text
  hide?: boolean            // Hide pin names in schematic
}

properties

Standard KiCad symbol properties:

interface KicadSymbolProperties {
  Reference?: KicadSymbolProperty   // Reference designator prefix (e.g., "U")
  Value?: KicadSymbolProperty       // Component value/name
  Footprint?: KicadSymbolProperty   // Associated footprint
  Datasheet?: KicadSymbolProperty   // Datasheet URL
  Description?: KicadSymbolProperty // Human-readable description
  ki_keywords?: KicadSymbolProperty // Search keywords
  ki_fp_filters?: KicadSymbolProperty // Footprint filter patterns
}

interface KicadSymbolProperty {
  value: string
  id?: number | string
  at?: { x: number | string; y: number | string; rotation?: number | string }
  effects?: {
    font?: {
      size?: { x: number | string; y: number | string }
      thickness?: number | string
    }
    justify?: string | string[]
    hide?: boolean
  }
}

Example Usage

<chip
  name="U1"
  footprint="soic8"
  pinLabels={{
    pin1: "VCC",
    pin2: "OUT",
    pin3: "GND",
    pin4: "IN"
  }}
  kicadSymbolMetadata={{
    symbolName: "LM358",
    inBom: true,
    onBoard: true,
    excludeFromSim: false,
    pinNames: {
      offset: 1.016,
      hide: false
    },
    pinNumbers: {
      hide: false
    },
    properties: {
      Reference: { value: "U" },
      Value: { value: "LM358" },
      Footprint: { value: "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm" },
      Datasheet: { value: "http://www.ti.com/lit/ds/symlink/lm358.pdf" },
      Description: { value: "Dual operational amplifier" },
      ki_keywords: { value: "dual opamp" },
      ki_fp_filters: { value: "SOIC*" }
    }
  }}
/>

kicadPinMetadata

The kicadPinMetadata property is used on <port /> elements to store KiCad-specific pin information. This includes the pin's electrical type, graphic style, and text sizing properties that are used when exporting to KiCad symbol files.

Type Definition

interface KicadPinMetadata {
  electricalType?: KicadPinElectricalType
  graphicStyle?: KicadPinGraphicStyle
  pinLength?: Distance
  nameTextSize?: Distance
  numberTextSize?: Distance
}

Properties

Property	Type	Description
`electricalType`	`KicadPinElectricalType`	Electrical characteristics of the pin
`graphicStyle`	`KicadPinGraphicStyle`	Visual representation style of the pin
`pinLength`	`Distance`	Physical length of the pin
`nameTextSize`	`Distance`	Text size for the pin name label
`numberTextSize`	`Distance`	Text size for the pin number label

electricalType

Specifies the electrical characteristics of the pin:

Value	Description
`"input"`	Input pin
`"output"`	Output pin
`"bidirectional"`	Bidirectional pin
`"tri_state"`	Tri-state pin
`"passive"`	Passive pin (resistors, capacitors, etc.)
`"free"`	Free pin (can connect to anything)
`"unspecified"`	Unspecified electrical type
`"power_in"`	Power input pin (VCC, GND)
`"power_out"`	Power output pin
`"open_collector"`	Open collector output
`"open_emitter"`	Open emitter output
`"no_connect"`	No connection pin

graphicStyle

Defines the visual representation of the pin in schematics:

Value	Description
`"line"`	Simple line (default)
`"inverted"`	Inverted (bubble)
`"clock"`	Clock input indicator
`"inverted_clock"`	Inverted clock
`"input_low"`	Active low input
`"clock_low"`	Active low clock
`"output_low"`	Active low output
`"falling_edge_clock"`	Falling edge triggered clock
`"nonlogic"`	Non-logic pin

Example Usage

<chip name="U1" footprint="soic8">
  <port
    name="pin1"
    pinNumber={1}
    kicadPinMetadata={{
      electricalType: "power_in",
      graphicStyle: "line",
      pinLength: "2.54mm",
      nameTextSize: "1.27mm",
      numberTextSize: "1.27mm"
    }}
  />
  <port
    name="pin2"
    pinNumber={2}
    kicadPinMetadata={{
      electricalType: "input",
      graphicStyle: "clock",
      pinLength: "2.54mm"
    }}
  />
  <port
    name="pin3"
    pinNumber={3}
    kicadPinMetadata={{
      electricalType: "output",
      graphicStyle: "inverted",
      pinLength: "2.54mm"
    }}
  />
</chip>

When to Use KiCad Metadata

Importing from KiCad

When you import components from KiCad, the converter tools automatically populate these metadata properties. This preserves the original KiCad information for reference and export compatibility.

Exporting to KiCad

When exporting your tscircuit design to KiCad format, these metadata properties are used to generate accurate .kicad_mod and .kicad_sym files that maintain compatibility with KiCad workflows.

Importing from KiCad - How to import KiCad components
KiCad Footprints - Using KiCad footprints with the kicad: prefix
Installing KiCad Libraries - Adding KiCad libraries to your project

Properties Overview​

kicadFootprintMetadata​

Type Definition​

Properties​

Top-level Properties​

properties​

attributes​

pads​

model​

Example Usage​

kicadSymbolMetadata​

Type Definition​

Properties​

Top-level Properties​

pinNumbers​

pinNames​

properties​

Example Usage​

kicadPinMetadata​

Type Definition​

Properties​

electricalType​

graphicStyle​

Example Usage​

When to Use KiCad Metadata​

Importing from KiCad​

Exporting to KiCad​

Related Documentation​

Properties Overview

kicadFootprintMetadata

Type Definition

Properties

Top-level Properties

properties

attributes

pads

model

Example Usage

kicadSymbolMetadata

Type Definition

Properties

Top-level Properties

pinNumbers

pinNames

properties

Example Usage

kicadPinMetadata

Type Definition

Properties

electricalType

graphicStyle

Example Usage

When to Use KiCad Metadata

Importing from KiCad

Exporting to KiCad

Related Documentation