Creating components

Component creation

A new component is created by using the create component command and specifying the pins parameter.

my_component = create component:
    pins: 2

at my_component

The code above creates a component object with 2 pins. The pins are automatically generated with a pin ID of 1 and 2 respectively.

Pin names can also be defined in the symbol object:

my_component = create component:
    pins: 
        1: "anode"
        2: "cathode"
at my_component

Properties during component creation

The following properties may be declared during component creation:

Name	Description
`pins`	If a single number is specified, the number of pins will be automatically created. Otherwise, pins with the given ID and names will be generated
`type`	Type of component, this may be used to determine the refdes group of the component. Supported values: `net, label, res, cap, ind, diode, conn`
`display`	Specify the graphic to display as the symbol of the component. If unspecified, a default rectangular symbol is generated.
`arrange`	If `display` is not specified, then the arrangement of pins must be specified.
`copy`	If this is set to `true`, whenever this component is referenced, a copy of the component will be created and used instead.
`refdes_prefix`	Custom reference designator prefix for the component (e.g., "U", "IC", "X"). Overrides the default prefix determined by the component `type`.
`params`	A map that specifies parameters of the component. This may be changed after component creation. Please see this page for more information.

Component graphical symbol

By default, the graphical symbol for the component is generated automatically. Pins are arranged in a zig-zag arrangement.

Default graphical symbol

my_component = create component:
    pins: 10

at my_component # need at least an `at` command to display the component in the schematic.

Specifying pin positions

The position of each component pin can be specified using the arrange parameter. Specify which pins are to be placed on the left, right, top, and bottom sides of the component. Each entry can reference a pin by its ID or by its name, and IDs, names, and blank-slot markers can be mixed freely in the same list.

my_component = create component:
    pins: 10
    arrange:
        left: 1, 2, 3, 4
        right: 5, 6, 7, 8, 9, 10
at my_component

Pins can also be arranged by name instead of by ID:

u1 = create component:
    pins:
        1: "VCC"
        2: "GND"
        3: "IN"
        4: "OUT"
    width: 300
    height: 300
    arrange:
        left: "IN"
        right: "OUT"
        top: "VCC"
        bottom: "GND"
at u1

If an entry does not match either a pin ID or a pin name, this is a hard error (Could not find pin ...) and the render fails. If the same pin is specified more than once in the arrange property — whether by repeating the same ID, the same name, or referencing the same pin by both its ID and its name — this produces a warning (Warning: Pin ... specified more than once in arrange property) rather than an error, and the render still succeeds.

Blank pin positions

To add spaces between pins, use the blank placeholder [<number] to specify a blank pin position.

my_component = create component:
    pins: 10
    arrange:
        left: [1], 1, [2], 2, 3
        right: 4, 5, 6, 7, 8, 9, 10
at my_component

Component pin types

The pin type of each component can be specified to provide more information about the pin. The following pin types are supported:

Pin Type	String Literal	Description
`Passive`	`"passive"`	Default type; no drive capability, connects freely (resistors, capacitors)
`Any`	`"any"`	Matches any other pin type; no connectivity restrictions
`Input`	`"input"`	Signal input; consumes a driven signal
`Output`	`"output"`	Signal output; drives a signal onto the net
`IO`	`"io"`	Bidirectional signal pin (input or output)
`HiZ`	`"hiz"`	High-impedance; can be tristated, does not actively drive
`OpenCollector`	`"open_collector"`	Open-collector/open-drain; pulls low, needs external pull-up
`OpenEmitter`	`"open_emitter"`	Open-emitter; pulls high, needs external pull-down
`Power`	`"power"`	Power net declarations (i.e. supply symbols, VCC, VDD)
`PowerReference`	`"power_reference"`	Reference potential net (e.g. GND symbol, component GND pins)
`PowerInput`	`"power_input"`	Consumes from a voltage rail (component VCC/VDD pins)
`PowerOutput`	`"power_output"`	Sources/drives a voltage rail (regulator output)
`NoConnect`	`"no_connect"`	Explicitly unconnected; suppresses ERC unconnected-pin warnings

Example:

my_component = create component:
    pins: 
        1: "IN", "input"
        2: "OUT", "output"
        3: "VCC", "power_input"
        4: "GND", "power_reference"

at my_component

The above component created has two power pins, one for pin 3 (VCC) and pin 4 (GND). Pin 1 is a signal input pin and pin 2 is a signal output pin.

Drawing custom component graphics

Custom component graphics is drawn using the create graphic command. Specfic drawing commands can be used to draw the component body and also define the placement of component pins.

width = 100
height = 100

my_component = create component:
    pins: 2
    display: create graphic(params):
        triangle: -width/2, 0, width/2, 0, height
        vline: width/2, -height/2, height
        hpin: 1, -width/2-100, 0, 100    # anode
        hpin: 2, width/2 + 100, 0, -100  # cathode
        label: params.refdes, 0, -80, fontSize=50, anchor="center", vanchor="bottom"

at my_component

The syntax for drawing commands are as follows: <command>: <arg1>, <arg2>, ...

`pin` command

pin: <pin ID: number>, <pin start x: number>, <pin start y: number>, <pin end x: number>, <pin end y: number>

The pin consists of the pin start point and the pin end point. The pin start point is where wires and other components connect to.

tip

If the pin type is not defined, the pin will have a pin type of "passive".

Example:

my_component = create component:
    pins: 2
    display: create graphic:
        rect: -100, -50, 200, 100
        pin: 1, -200, 0, -100, 0
        pin: 2, 200, 0, 100, 0
        path: ("M", 125, -50, "L", 200, -50, 
               "M", 150, -75, "L", 125, -50, "L", 150, -25)
        path: ("M", -125, -50, "L", -200, -50, 
               "M", -150, -75, "L", -125, -50, "L", -150, -25)

at my_component pin 1
wire left 100

at my_component pin 2
wire right 100

In the example above, the arrows indicate the direction of the pins. When building circuits, wires and other components are always connected at the start of the pin. In the example above, the wires are connected at side of the pin without the arrow-head.

`pin` command with pin name

pin: <pin ID: number>, <pin name: string>, <pin type: string>, <pin start x: number>, <pin start y: number>, <pin end x: number>, <pin end y: number>

This command displays the pin name beside the pin and the pin name is placed at the end point of the pin.

Example:

my_component = create component:
    pins: 2
    display: create graphic:
        rect: -100, -50, 200, 100
        pin: 1, "A", "passive", -200, 0, -100, 0
        pin: 2, "B", "passive", 200, 0, 100, 0
        path: "M", 125, -50, "L", 200, -50, \
               "M", 150, -75, "L", 125, -50, "L", 150, -25
        path: "M", -125, -50, "L", -200, -50,  \
               "M", -150, -75, "L", -125, -50, "L", -150, -25

at my_component pin 1
wire left 100

at my_component pin 2
wire right 200

In the above example, the pin name is displayed beside the pins and the pins are defined with a type of "passive".

Additional properties:

Set display_id=false to skip drawing of pinId beside the pin
Set display_name=false to skip drawing of name beside the pin

`hpin` command

This command is a simplification of the pin command and is used to draw horizontal pins.

hpin: <pin id>, <pin start x: number>, <pin start y: number>, <pin x length>

With pin name and type:

hpin: <pin id>, <pin name: string>, <pin type: string>, <pin start x: number>, <pin start y: number>, <pin x length>

See this table for the possible pin types.

`vpin` command

This command is a simplification of the pin command and is used to draw vertical pins.

vpin: <pin id>, <pin start x: number>, <pin start y: number>, <pin y length>`

With pin name and type:

vpin: <pin id>, <pin name: string>, <pin type: string>, <pin start x: number>, <pin start y: number>, <pin y length>`

See this table for the possible pin types.

`rect` command

Draws a rectangle by specifying the top-left coordinate of the rectangle, followed by the width and height.

rect: <x: number>, <y: number>, <width: number>, <height: number>

`crect` command

Draws a rectangle by specifying the center of the rectangle, followed by the width and height.

crect: <center x: number>, <center y: number>, <width: number>, <height: number>

`label` command

label: <text: string>, <x: number>, <y: number>, <...named parameters>

Currently, only the following named parameters are accepted:

fontSize: number
anchor: One of "left", "center", "right",
vanchor: One of "top", "center", "bottom"

`hline` command

Draws a horizontal line of a given length starting from the point.

hline: <x: number>, <y: number>, <length: number>

`vline` command

Draws a vertical line of a given length starting from the specified point.

vline: <x: number>, <y: number>, <length: number>

`arc` command

Draws a section of a circle at a given location and radius. The section is drawn in a clockwise direction from the starting angle to the ending angle.

arc: <center x>, <center y>, <radius>, <starting angle>, <ending angle>

`path` command

path: <... array of drawing instructions>

The path command is similar to path in the SVG spec.

Example:

path: "M", 0, 0, "L", 10, 10

This path command moves the drawing cursor to (0, 0) and draws a line until (10, 10)

path: "M", 100, 100, "L", 200, 200, "L", 200, 100

This path commands starts at (100, 100), draws a line until (200, 200) and a further line until (200, 100)

At the moment, only the "M" and "L" instructions are supported.

`fill` command

Sets the current fill color used for drawing closed shapes (circles, rectangles, paths, etc.)

`text_color` command

Sets the current text color used for drawing text

`line_color` command

Sets the current line color used for drawing line

`line_width` command

Sets the current line width used for drawing lines

Light/dark theming for `fill`, `text_color`, `line_color`

Each of fill, text_color and line_color accepts a single color:

line_color: "#333333"

or a light/dark pair, given as a dark= keyword argument alongside the light color:

line_color: "#cccccc", dark="#333333"

This renders as an inline CSS light-dark(#cccccc, #333333) value, so the color automatically follows the viewer's light/dark theme when the SVG is opened in a browser.

An optional var=<name> argument additionally exposes the color as a named CSS custom property, instead of an inline value:

line_color: "#cccccc", dark="#333333", var="my-line-color"

This compiles the element's color to var(--cs-my-line-color), and adds a declaration to the document's :root block:

:root {
  --cs-my-line-color: light-dark(#cccccc, #333333);
}

Anything consuming the exported SVG can then override the color for that document by setting --cs-my-line-color on the SVG (or an ancestor element) in its own stylesheet - without needing to touch the individual elements that use it:

svg {
  --cs-my-line-color: #ff0000;
}

var= names share the --cs- prefix with Circuitscript's own built-in theme variables (--cs-line-color, --cs-text-color, --cs-wire-color, etc.), so a name that collides with one of those is rejected - pick a name that isn't one of the built-in color roles.

Note that PDF and KiCad export have no concept of light/dark themes: both always resolve a themed color down to its light value.

Component creation​

Properties during component creation​

Component graphical symbol​

Default graphical symbol​

Specifying pin positions​

Blank pin positions​

Component pin types​

Drawing custom component graphics​

pin command​

pin command with pin name​

Additional properties:​

hpin command​

vpin command​

rect command​

crect command​

label command​

hline command​

vline command​

arc command​

path command​

fill command​

text_color command​

line_color command​

line_width command​

Light/dark theming for fill, text_color, line_color​

Component creation

Properties during component creation

Component graphical symbol

Default graphical symbol

Specifying pin positions

Blank pin positions

Component pin types

Drawing custom component graphics

`pin` command

`pin` command with pin name

Additional properties:

`hpin` command

`vpin` command

`rect` command

`crect` command

`label` command

`hline` command

`vline` command

`arc` command

`path` command

`fill` command

`text_color` command

`line_color` command

`line_width` command

Light/dark theming for `fill`, `text_color`, `line_color`