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

> Master Font Awesome 7 duotone icon customization with our guide to primary and secondary opacity. Control transparency easily using CSS custom properties. Learn more now.

- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

```css
.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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

```html
<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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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:

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

```

Alternatively, use a dedicated class:

```html
<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:

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

```

The CSS implementation in [`styles.css`](https://github.com/FortAwesome/Font-Awesome/blob/main/styles.css) handles this swap:

```css
.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:

```html
<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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss) and applied via [`styles.css`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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.