Font Awesome 7 Duotone Icons Customization: Primary and Secondary Opacity Guide

Font Awesome 7 duotone icons use CSS custom properties --fa-primary-opacity and --fa-secondary-opacity to control the transparency of the two overlapping SVG layers, defaulting to 1 and 0.4 respectively.

Font Awesome 7 implements duotone icons as two distinct SVG paths rendered in a single container. The primary path sits atop the secondary path, creating a two-tone effect. According to the FortAwesome/Font-Awesome source code, the library exposes these layers through CSS custom properties defined in scss/_variables.scss and applied via js-packages/@fortawesome/fontawesome-svg-core/styles.css.

How Font Awesome 7 Duotone Icons Work

Duotone icons consist of two overlapping vector paths within a single SVG element. The primary layer renders the main icon details at full opacity by default, while the secondary layer provides background or shadow elements at reduced opacity.

The CSS architecture relies on specific classes targeting these layers:

.svg-inline--fa .fa-primary {
  fill: var(--fa-primary-color, currentColor);
  opacity: var(--fa-primary-opacity, 1);
}

.svg-inline--fa .fa-secondary {
  fill: var(--fa-secondary-color, currentColor);
  opacity: var(--fa-secondary-opacity, 0.4);
}

These rules appear in the generated css/svg.css and the core JavaScript package styles, ensuring consistent rendering across implementation methods.

CSS Custom Properties for Opacity Control

Font Awesome 7 exposes four primary CSS variables for duotone customization:

Variable	Default	Purpose
--fa-primary-opacity	1	Controls transparency of the primary (top) layer
--fa-secondary-opacity	0.4	Controls transparency of the secondary (bottom) layer
--fa-primary-color	currentColor	Sets fill color for the primary layer
--fa-secondary-color	currentColor	Sets fill color for the secondary layer

These variables cascade through the DOM, allowing inheritance from root definitions down to individual icon elements.

Customization Methods

Global Opacity Override

Redefine the CSS variables on the :root selector or a container element to affect all duotone icons within scope:

<style>
  :root {
    --fa-primary-opacity: 0.8;
    --fa-secondary-opacity: 0.2;
  }
</style>

<i class="fa-duotone fa-heart"></i>

This approach modifies the default values defined in scss/_variables.scss without requiring changes to the source files.

Per-Icon Opacity Customization

Apply inline styles or specific CSS classes to individual icons for targeted adjustments:

<i class="fa-duotone fa-star" 
   style="--fa-primary-opacity: 0.6; --fa-secondary-opacity: 0.1;"></i>

Alternatively, use a dedicated class:

<style>
  .dimmed-secondary {
    --fa-primary-opacity: 0.9;
    --fa-secondary-opacity: 0.3;
  }
</style>

<i class="fa-duotone fa-moon dimmed-secondary"></i>

Swapping Primary and Secondary Opacity

Font Awesome 7 provides the fa-swap-opacity utility class to invert the opacity values between layers. When applied to the SVG element, the primary layer adopts the secondary opacity value and vice versa:

<i class="fa-duotone fa-envelope fa-swap-opacity"></i>

The CSS implementation in styles.css handles this swap:

.svg-inline--fa.fa-swap-opacity .fa-primary {
  opacity: var(--fa-secondary-opacity, 0.4);
}

.svg-inline--fa.fa-swap-opacity .fa-secondary {
  opacity: var(--fa-primary-opacity, 1);
}

For interactive effects, combine this with hover states:

<style>
  .swap-on-hover:hover {
    --fa-primary-opacity: 0.4;
    --fa-secondary-opacity: 1;
  }
</style>

<i class="fa-duotone fa-bell swap-on-hover"></i>

Source Code Implementation

The opacity system originates in the SCSS variables file and propagates through the build pipeline:

1. scss/_variables.scss – Defines the default opacity values as SCSS variables that generate the CSS custom properties.

2. js-packages/@fortawesome/fontawesome-svg-core/styles.css – Contains the runtime CSS rules applying the variables to .fa-primary and .fa-secondary classes.

3. css/svg.css – The production-ready stylesheet distributed to browsers, implementing the same variable-based opacity controls.

This architecture ensures that opacity values remain configurable at runtime without requiring JavaScript manipulation of SVG attributes or recompilation of the icon library.

Summary

• Font Awesome 7 duotone icons render as two SVG layers controlled by CSS custom properties --fa-primary-opacity and --fa-secondary-opacity.
• Default values are 1 (primary) and 0.4 (secondary), defined in scss/_variables.scss and applied via styles.css.
• Global customization requires overriding the CSS variables on :root or container elements.
• Per-icon adjustments work through inline styles or specific CSS selectors targeting individual elements.
• The fa-swap-opacity class inverts the opacity values between primary and secondary layers without manual variable reassignment.

Frequently Asked Questions

How do I change the opacity of only one specific duotone icon?

Set the CSS variables directly on that icon using an inline style attribute or a unique CSS class. For example: style="--fa-primary-opacity: 0.7; --fa-secondary-opacity: 0.3;". Because Font Awesome 7 uses CSS custom properties, these values inherit through the DOM and apply immediately to the SVG paths.

What is the default opacity for Font Awesome 7 duotone icons?

The primary layer defaults to 1 (fully opaque), while the secondary layer defaults to 0.4 (40% opacity). These values originate in the $primary-opacity and $secondary-opacity SCSS variables within scss/_variables.scss, which compile to the CSS custom properties --fa-primary-opacity and --fa-secondary-opacity.

Can I swap the primary and secondary opacity values without manually changing the CSS variables?

Yes. Add the fa-swap-opacity class to your duotone icon element. This class triggers CSS rules that apply the secondary opacity value to the primary path and the primary opacity value to the secondary path. This is useful for hover effects or when you want the background layer to appear more prominent than the foreground layer.

Does changing opacity affect the icon size or positioning?

No. Adjusting --fa-primary-opacity or --fa-secondary-opacity only modifies the visual transparency of the respective SVG paths. The viewBox, dimensions, and spatial positioning of the icon remain unchanged because the opacity property affects only the alpha channel of the fill color, not the geometry or layout of the SVG element.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}