WireViz bill of materials and additional components

Automatic connector, cable and bundle BOM entries; every additional-component field; quantity multipliers; manual items; and aggregation rules.

WireViz creates a bill of materials from the instantiated harness. You can attach related parts to a connector or cable and add independent items at document level. This page describes the actual 0.4.1 BOM generator and quantity multiplier implementation.

Automatic entries

Component	Automatic quantity	Description includes
Connector	One per instantiated connector	Type, subtype, pin count when shown, and body color when supplied.
Regular cable	Cable `length`, with `length_unit`	Type, wire count, gauge when present, shield indication, and outer color.
Bundle	Bundle `length` for each wire	Type, gauge when present, and individual wire color.

Only definitions referenced by connections are instantiated. Unused library definitions contribute no automatic parts. A cable with omitted length has the native default length 0, so its automatic BOM quantity is zero. Enter the intended physical length; diagram geometry does not supply it.

ignore_in_bom: true suppresses the parent connector/cable's own automatic entry. Its additional_components are still processed. Likewise, hiding a component's name removes its designator from the BOM's designator list but does not remove its quantity.

Attach contacts and seals to a connector

connectors:
  X1:
    type: Four-position housing
    pincount: 4
    additional_components:
      - type: Crimp contact
        mpn: CONTACT-01
        qty: 1
        qty_multiplier: populated
      - type: Cavity seal
        mpn: SEAL-01
        qty: 1
        qty_multiplier: unpopulated
  X2:
    pincount: 2
cables:
  W1:
    colors: [RD, BK]
    length: 0.8
connections:
  - - X1: [1, 2]
    - W1: [1, 2]
    - X2: [1, 2]

Here X1 has two populated positions and two unpopulated positions, producing two contacts and two seals. Those product identifiers are placeholders, not validated supplier parts. The associated parts also appear inside the native component box; options.mini_bom_mode controls how much detail is displayed there.

Complete additional-component schema

The same mapping is accepted in a connector or cable's additional_components list.

Field	Value	Default or meaning
`type`	Text, required	Main part description.
`subtype`	Text	Extra description appended to type.
`qty`	Integer or decimal	Default `1`; base quantity before multiplication.
`qty_multiplier`	String	Optional parent-derived multiplier from the table below.
`unit`	String	Optional unit label; not inferred from the multiplier.
`pn`	Text	Internal part number.
`manufacturer`	Text	Manufacturer name.
`mpn`	Text	Manufacturer part number.
`supplier`	Text	Supplier name.
`spn`	Text	Supplier part number.
`bgcolor`	Color	Background of this entry within the native diagram box.

The resulting quantity is qty × multiplier. Omitting the multiplier uses 1. A parent-derived multiplier of zero omits that additional component. A base qty of zero is not the same filtering condition and can leave a zero-quantity BOM row.

Quantity multipliers, precisely

Parent	Multiplier	0.4.1 value
Connector	`pincount`	Declared or inferred pin count.
Connector	`populated`	Number of unique activated pin IDs, including pins activated by loops.
Connector	`unpopulated`	`max(0, pincount - populated)`.
Cable/bundle	`wirecount`	Number of ordinary conductors, excluding the shield.
Cable/bundle	`terminations`	Length of the cable's resolved connection-record list.
Cable/bundle	`length`	Stored cable length.
Cable/bundle	`total_length`	Stored length multiplied by wire count.

The name terminations can be misleading: one connection record may describe a conductor connected at both ends. A single three-lane connector–cable–connector set produces three records, not six physical ends. Separate one-ended sets or shield records can change that count. For predictable physical terminal quantities, use connector populated counts or an explicit quantity after reviewing the topology.

Multipliers do not convert units. For sleeve material calculated from cable length, provide an appropriate unit explicitly and ensure it matches the cable's stored length unit. Invalid multiplier names, including a cable multiplier on a connector, raise an error.

Independent BOM items

Use additional_bom_items for parts with no parent diagram box, such as packaging or an independently specified jumper. This fragment shows the full item shape:

additional_bom_items:
  - description: Identification label
    qty: 2
    unit: pcs
    designators: [LABEL-A, LABEL-B]
    pn: LABEL-SET
    manufacturer: Example Labels
    mpn: LABEL-20X8
    supplier: Example Distributor
    spn: STOCK-123

description supplies the item description. qty defaults to 1; unit, designators, and the five product-information fields are optional. Prefer a list of strings for designators. This form has no type, subtype, qty_multiplier, or diagram bgcolor field and is not drawn as a standalone node.

Grouping, columns, and rounding

Rows are grouped when their normalized description, unit, internal part number, manufacturer, manufacturer part number, supplier, and supplier part number all match. Quantities are summed; designators are deduplicated and sorted. Whitespace is cleaned before grouping. Different units remain separate groups, and different supplier data can keep otherwise identical products separate.

The grouped quantity is rendered as an integer when integral, otherwise rounded to three decimal places. Each sorted BOM row receives a generated numeric ID. These IDs are output references and can change when the document changes; use your own pn for a stable internal identifier.

The table always includes ID, description, quantity, unit, and designators. Optional purchasing columns appear when used by at least one row. The native CLI exports this table as TSV and includes it in HTML. See CLI outputs and options.