:experimental:

[[schematic-design-variants]]
== Design variants

Many products share a common circuit board but are sold in different configurations.
A consumer router might come in WiFi-only and WiFi+Bluetooth models; an industrial
controller might ship with different sensor front-ends for different markets.
Traditionally, each configuration requires its own schematic and board, which means
duplicated work and diverging designs.

Design variants solve this problem.  A variant is a named set of overrides applied on
top of a single base design.  Each variant can change which components are populated,
swap field values such as the component value or footprint, and control which components
appear in the BOM or position files.  The base design remains the source of truth, and
each variant records only what differs.

NOTE: Design variants are an assembly-level feature.  All variants share the same
      copper, the same netlist, and the same board outline.  If your product
      configurations require different copper or different board shapes, you need
      separate board designs.

[[understanding-design-variants]]
=== Understanding design variants

Every KiCad project starts with a single implicit variant called the **default
variant**.  The default variant represents the base design with no overrides.  When you
create additional named variants, each one begins as an exact copy of the default and
can then be customized independently.

Variant data is stored per symbol instance in the schematic.  This means that the same
symbol used in different places in a hierarchical design can have different variant
overrides at each location.  When you run **Update PCB from Schematic**, the variant
data is transferred to the corresponding footprints on the board.

The active variant is selected from a dropdown in the main toolbar of both the
Schematic Editor and the PCB Editor.  Selecting a variant immediately updates the
display to reflect that variant's overrides, including field text, DNP markings, and
exclusion indicators.

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

[[types-of-variation]]
=== Types of variation

[[fitted-and-not-fitted]]
==== Fitted and not fitted

The most common use of variants is to mark certain components as **Do Not Populate**
(DNP) in one variant while keeping them fitted in another.  A component marked DNP in
the active variant is displayed with an X through it on the schematic and on the
fabrication layers of the board.

For example, a Bluetooth module and its supporting passives might be fitted in a
"WiFi+BT" variant but marked DNP in a "WiFi-only" variant.

[[field-overrides]]
==== Field overrides

Variants can override any symbol field on a per-component, per-variant basis.  Common
uses include changing the **Value** field to select a different resistance or capacitance,
changing the **Footprint** field to substitute a different package, or updating a custom
**Manufacturer Part Number** field to point to an alternate sourcing option.

When a field has been overridden for the active variant, the Symbol Fields Table
highlights the cell with a colored background so you can see at a glance which values
differ from the base design.

NOTE: The **Reference** field cannot be overridden by a variant.  Changing a reference
      designator would effectively create a different netlist, which is outside the
      scope of assembly variants.

[[excluding-from-outputs]]
==== Excluding from outputs

In addition to the DNP flag, each variant can independently control whether a component
is excluded from:

* **BOM** -- the component will not appear in the bill of materials for that variant
* **Position files** -- the component will be omitted from pick-and-place output
* **Simulation** -- the component will be excluded from SPICE simulation

These flags are independent of each other and independent of DNP.  For instance, you
might want a test point to appear in the BOM but not in the position file for a
specific variant.

[[sheet-level-variants]]
==== Sheet-level variants

Variant overrides can also be applied to entire hierarchical sheets.  Marking a sheet
as DNP for a variant marks every component on that sheet (and all nested sub-sheets) as
not fitted.  This is useful when a hierarchical sheet represents a functional block that
is present in some product configurations and absent in others.

Sheet-level exclusion flags (BOM, position files, simulation) work the same way,
applying to all components within the sheet for that variant.

[[creating-and-managing-variants]]
=== Creating and managing variants

[[creating-a-new-variant]]
==== Creating a new variant

There are two ways to create a new variant:

* **From the toolbar:** Click the variant selector dropdown in the main toolbar and
  choose **Add New Design Variant...** at the bottom of the list.  A dialog appears
  where you enter a name and an optional description.

image::images/variant_add_dialog.png[scaledwidth="40%"]

* **From the Symbol Fields Table:** Open the Symbol Fields Table
  (**Tools** -> **Bulk Edit Symbol Fields...**), then click the **Add** button
  in the variant list on the left side of the dialog.

Variant names must be unique (comparison is case-insensitive) and cannot use the
reserved name `<Default>`.

[[switching-between-variants]]
==== Switching between variants

Select the desired variant from the dropdown in the main toolbar.  The schematic view
updates immediately to show the overridden field values and DNP markings for that
variant.  Selecting `<Default>` returns to the base design with no overrides.

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

[[managing-variants-in-the-symbol-fields-table]]
==== Managing variants in the Symbol Fields Table

The Symbol Fields Table provides a variant list on the left side of the dialog with
buttons for common management operations:

* **Add** -- create a new variant (same dialog as the toolbar method)
* **Delete** -- remove the selected variant and all of its overrides
* **Rename** -- change the name of the selected variant
* **Copy** -- duplicate the selected variant under a new name, preserving all of its
  overrides

NOTE: The default variant cannot be deleted, renamed, or copied.  It always exists as
      the base design.

Selecting a variant in the list switches the grid to display that variant's data.
Any pending edits to the previously active variant are committed automatically.

image::images/variant_fields_table_panel.png[scaledwidth="90%"]

[[editing-variant-data]]
=== Editing variant data

When a non-default variant is selected in the toolbar, editing the schematic modifies
that variant rather than the base design.  Edit variant data in bulk through the Symbol
Fields Table, or one symbol at a time with the normal schematic editing tools.

[[editing-fields-in-the-symbol-fields-table]]
==== Editing fields in the Symbol Fields Table

The Symbol Fields Table is the primary tool for bulk-editing variant data.  Select a
variant from the list on the left, then edit cell values directly in the grid.  The
grid shows the effective value for each field in the selected variant.

Cells that differ from the default variant are highlighted with a colored background
(yellow in light themes, gold in dark themes).  This makes it easy to review all
overrides at a glance.

To set a field back to its default value, clear the cell or set it to match the default
variant's value.  The override is removed and the highlight disappears.

The same grid supports editing DNP and exclusion flags.  The **DNP**,
**Exclude from BOM**, **Exclude from Position Files**, and **Exclude from Simulation**
columns contain checkboxes that can be toggled per variant.

[[editing-variants-in-the-canvas]]
==== Editing variants in the canvas

While a non-default variant is active, any edit made in the canvas updates that
variant's overrides.  The base design is unchanged.  This applies to all the normal
editing tools:

* The Properties panel on the left shows the effective field values and attribute
  flags for the active variant.  Edits here update the variant's overrides for the
  selected symbol.
* The Symbol Properties dialog (double-click a symbol) shows the active variant name
  in its title bar so you know edits apply to that variant.
* In-place field edits on the canvas and attribute changes from the right-click menu
  also apply to the active variant.

To mark a component as DNP for a specific variant, select the variant from the toolbar
dropdown, select the symbol, and check the **Do not populate** checkbox in the
Properties panel.  The symbol is immediately drawn with an X overlay; switching back to
the default variant shows the symbol without the X (assuming it is fitted in the base
design).  The same procedure works for the **Exclude from BOM**,
**Exclude from position files**, and **Exclude from simulation** checkboxes.

For bulk editing across many components at once, use the Symbol Fields Table.

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

[[bom-export-with-variants]]
==== BOM export with variants

Open the Symbol Fields Table via **Tools** -> **Generate Bill of Materials...**.
The exported BOM reflects the active variant's field values and respects its DNP and BOM exclusion flags.

To generate separate BOM files for each variant automatically, use the `${VARIANT}`
text variable in the output file path.  For example, an output path of
`bom_${VARIANT}.csv` produces `bom_WiFi-only.csv` and `bom_WiFi-BT.csv` when the
project has those two variants defined.

[[schematic-plotting-with-variants]]
==== Schematic plotting with variants

The Plot Schematic dialog (**File** -> **Plot...**) includes a variant selector.
Choose a variant to generate schematic plots that show the correct field values and
DNP markings for that configuration.  The default variant produces a plot of the base
design.

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

Several `sch export` commands in the KiCad command-line interface support the
`--variant` argument, including `sch export bom`, `sch export pdf`, `sch export svg`,
`sch export dxf`, `sch export ps`, and `sch export netlist`.  This enables scripted
generation of schematic output for one or more variants.

To export a schematic PDF for a specific variant:

[source,shell]
----
kicad-cli sch export pdf --variant "WiFi-only" my_project.kicad_sch
----

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 sch export pdf \
    --variant "WiFi-only" \
    --variant "WiFi-BT" \
    -o "schematic_${VARIANT}.pdf" \
    my_project.kicad_sch
----

When `--variant` is not specified, the default variant is used.

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

[[variant-text-variables]]
=== Text variables

Two text variables are available for use in title blocks, text labels, and other text
items:

* `${VARIANT}` -- resolves to the name of the currently active variant, or an empty
  string when the default variant is active
* `${VARIANT_DESC}` -- resolves to the description of the currently active variant

These variables update dynamically when you switch variants and are included in plotted
output, making it straightforward to identify which variant a printed schematic
represents.

[[transferring-variants-to-pcb]]
=== Transferring variants to the PCB editor

Variant data is transferred from the schematic to the PCB when you run **Update PCB
from Schematic** (**Tools** -> **Update PCB from Schematic...**).  The update process
synchronizes DNP flags, exclusion flags, and field overrides from each symbol to the
corresponding footprint.  This happens for every variant.

If a variant override has been removed in the schematic, the corresponding footprint
override is reset to the base value during the update.

NOTE: Variant data flows from the schematic to the PCB, not the other way around.
      Always define and edit variants in the Schematic Editor, then update the PCB.

After the update, the PCB Editor's toolbar variant selector is populated with the same
variant names.  See xref:../pcbnew/pcbnew.adoc#pcb-design-variants[Design variants] in
the PCB Editor manual for details on working with variants in the board layout.
