:experimental:

[[pcb-design-variants]]
== Design variants

Design variants allow a single PCB to represent multiple product configurations.
Variants are defined in the Schematic Editor and transferred to the board through
**Update PCB from Schematic**.  The PCB Editor provides tools for viewing variant
effects, selecting the active variant, and generating variant-specific manufacturing
output.

For information on creating variants and editing variant data, see
xref:../eeschema/eeschema.adoc#schematic-design-variants[Design variants] in the
Schematic Editor manual.

[[selecting-a-variant-in-the-pcb-editor]]
=== Selecting a variant in the PCB editor

The main toolbar contains a variant selector dropdown, identical in behavior to the one
in the Schematic Editor.  Selecting a variant updates the board view to reflect that
variant's component states.

image::images/pcb_variant_toolbar_selector.png[scaledwidth="70%"]

When a variant is active:

* Components marked DNP in that variant display an X on the fabrication layers.
* Field text (Value, Footprint, custom fields) reflects the variant's overrides.
* Text items using `${VARIANT}` or `${VARIANT_DESC}` resolve to the active variant's
  name and description.

Selecting `<Default>` returns to the base design with no overrides applied.

[[viewing-variant-effects]]
=== Viewing variant effects

[[component-visibility-and-dnp]]
==== Component visibility and DNP

When a variant is active, components marked DNP for that variant are displayed with an X
drawn across them on the fabrication layers (F.Fab and B.Fab).  This matches the
behavior of the base design's DNP attribute, but is controlled per-variant.

The board view updates in real time as you switch between variants, so you can quickly
compare which components are fitted in each configuration.

[[three-d-viewer]]
==== 3D viewer

The 3D viewer respects the active variant.  Components marked DNP in the current
variant are hidden from the 3D view, giving you an accurate visual representation of
how the assembled board will look for each product configuration.

To see a specific variant in the 3D viewer, select it from the toolbar dropdown in the
PCB Editor before opening (or while viewing) the 3D model.

[[footprint-properties]]
==== Footprint properties

When a non-default variant is active, both the Properties panel and the Footprint
Properties dialog (double-click a footprint) show the variant's overrides instead of
the base design values.  This includes field values, the DNP attribute, and the
exclusion flags.  Edit variant overrides for individual footprints through either the
panel or the dialog.

[[pcb-generating-variant-aware-outputs]]
=== Generating variant-aware outputs

Several output dialogs in the PCB Editor include a variant selector.  Choosing a
variant before generating output ensures the files reflect that variant's component
states.

[[gerber-and-fabrication-output]]
==== Gerber and fabrication output

The Plot dialog (**File** -> **Plot...**) includes a **Variant** dropdown.
Select a variant to produce Gerber files that reflect DNP markings on the fabrication
layers for that configuration.

When the **Indicate DNP on fabrication layers** option is enabled, components marked
DNP in the selected variant are drawn with an X on F.Fab and B.Fab layers, just as
they appear in the editor view.

[[position-files]]
==== Position files

The Component Placement dialog (**File** -> **Fabrication Outputs** ->
**Component Placement (.pos, .gbr)...**) includes a variant selector.  Components
marked DNP or excluded from position files in the selected variant are omitted from
the output.

This allows you to generate a separate pick-and-place file for each product
configuration, containing only the components that should be assembled for that
variant.

[[three-d-model-export]]
==== 3D model export (STEP/VRML)

The 3D model export dialog (**File** -> **Export** ->
**STEP/GLB/BREP/XAO/PLY/STL...**) includes a variant selector.  Components marked
DNP in the selected variant are excluded from the exported 3D model, producing an
accurate mechanical representation of the assembled board for that variant.

[[odb-and-ipc2581]]
==== ODB++ and IPC-2581

The ODB++ and IPC-2581 export formats support variant selection through the
command-line interface (see <<command-line-variant-support>> below).  Use the
`--variant` argument with `pcb export odb` or `pcb export ipc2581` to produce
variant-specific manufacturing data.

[[command-line-variant-support]]
=== Command-line variant support

All PCB export commands in the KiCad command-line interface support the `--variant`
argument.  This enables scripted and automated generation of output files for multiple
variants.

To export Gerber files for a specific variant:

[source,shell]
----
kicad-cli pcb export gerbers --variant "WiFi-only" my_board.kicad_pcb
----

To generate output for multiple variants in a single command, specify `--variant`
more than once and use `${VARIANT}` in the output path to produce separate files:

[source,shell]
----
kicad-cli pcb export gerbers \
    --variant "WiFi-only" \
    --variant "WiFi-BT" \
    -o "gerbers_${VARIANT}/" \
    my_board.kicad_pcb
----

This produces two sets of Gerber files in `gerbers_WiFi-only/` and `gerbers_WiFi-BT/`.

The same pattern works with all export commands that support variants, including
`pcb export step`, `pcb export pos`, `pcb export dxf`, `sch export bom`, and others.
When `--variant` is not specified, the default variant is used.

NOTE: The `${VARIANT}` text variable in output paths is expanded at export time
      and is independent of the `${VARIANT}` text variable used in schematic and
      board text items.

For a complete list of export commands and their variant-related options, see the
xref:../cli/cli.adoc[Command-Line Interface] reference.
