Font Awesome 7 CSS Custom Properties for Theming: Complete Guide

Font Awesome 7 exposes dozens of CSS custom properties in js-packages/@fortawesome/fontawesome-svg-core/styles.css that control font families, colors, sizing, and animations, allowing you to theme icons globally or per-component without modifying the library source code.

Font Awesome 7 ships with a comprehensive theming engine built on CSS custom properties (variables). According to the FortAwesome/Font-Awesome repository, these variables drive every visual aspect of the icons and can be overridden at the global, component, or per-icon level to match your brand or dark mode requirements.

Core Theming Variables Architecture

The library declares variables on the :root and :host selectors in js-packages/@fortawesome/fontawesome-svg-core/styles.css, making them available throughout your application. The same values are mirrored in scss/_variables.scss for projects using the Sass build pipeline.

Font Family Definitions

Style-specific font stacks are defined via variables for each icon weight:

:root, :host {
  --fa-font-solid: normal 900 1em/1 'Font Awesome 7 Free';
  --fa-font-regular: normal 400 1em/1 'Font Awesome 7 Free';
  --fa-font-brands: normal 400 1em/1 'Font Awesome 7 Brands';
}

Visual and Layout Variables

Sizing and spacing controls include:

• --fa-width: Default 1.25em (base icon width; set to auto when using .fa-width-auto)
• --fa-pull-margin: Default 0.3em (horizontal margin for .fa-pull-left and .fa-pull-right)

Color system for layered and themed icons:

• --fa-primary-color: Default currentColor
• --fa-secondary-color: Default currentColor
• --fa-inverse: Default #fff (white used by .fa-inverse class)
• --fa-counter-background-color: Default #ff253a
• --fa-counter-color: Default #fff

Animation timing variables:

• --fa-animation-duration: Default 1s
• --fa-beat-scale: Default 1.25

Three Levels of Theming Implementation

Because Font Awesome 7 consumes these variables throughout its CSS—width: var(--fa-width), fill: var(--fa-primary-color), etc.—overrides propagate instantly at three specificity levels.

1. Global Theme Overrides

Define variables on :root to affect every icon on the page:

:root {
  --fa-primary-color: #fff;
  --fa-secondary-color: #bbb;
  --fa-inverse: #000;
  --fa-counter-background-color: #222;
}

This configuration creates a dark mode where all icons render with light strokes, muted secondary layers, and dark inverse backgrounds.

2. Component-Scoped Themes

Apply a custom class to a container to theme only descendant icons:

.brand-theme {
  --fa-primary-color: #ff6600;
  --fa-secondary-color: #0044cc;
}

<div class="brand-theme">
  <i class="fa-solid fa-camera"></i>
  <i class="fa-solid fa-music"></i>
</div>

Only icons inside .brand-theme adopt the brand orange and blue palette.

3. Per-Icon Overrides

Use inline styles or specific selectors for single-icon customization:

<i class="fa-solid fa-heart fa-2x"
   style="--fa-primary-color:#e00; --fa-secondary-color:#800; --fa-width:3em;">
</i>

The heart icon renders at 3× its default width with a bright red primary layer and darker secondary shade.

Practical Customization Examples

Customizing Badge Counters

Override counter colors for notification badges used with .fa-layers-counter:

.fa-layers-counter {
  --fa-counter-background-color: #333;
  --fa-counter-color: #ff0;
}

All numeric counters display with a dark background and yellow text.

Adjusting Animation Speed

Slow down the default spin animation:

.fa-spin {
  --fa-animation-duration: 4s;
}

All spinning icons now rotate at one-quarter the default speed.

SCSS Integration

For projects compiling from source, reference the variables in scss/_variables.scss. The file scss/_functions.scss provides helper functions to ensure your custom Sass build maintains parity with the CSS custom property definitions.

Key Source Files in FortAwesome/Font-Awesome

• js-packages/@fortawesome/fontawesome-svg-core/styles.css: Declares the full set of CSS custom properties and consumes them throughout the core icon styles.
• scss/_variables.scss: SCSS source mirroring the CSS variables for Sass-based projects.
• scss/_functions.scss: Helper functions used by the SCSS build to reference variables.
• css/fontawesome.css: The compiled stylesheet that end-users typically include; imports the variable definitions.

Summary

• Font Awesome 7 defines CSS custom properties in js-packages/@fortawesome/fontawesome-svg-core/styles.css that control every visual aspect of icons.
• Key variables include --fa-primary-color, --fa-secondary-color, --fa-width, --fa-inverse, and animation controls like --fa-animation-duration.
• Theme globally via :root, scope to components with custom classes, or target single icons with inline styles.
• The same variable set exists in scss/_variables.scss for projects using the Sass build pipeline.
• All changes propagate instantly because the library uses var() references throughout its rule definitions.

Frequently Asked Questions

How do I change the default icon color in Font Awesome 7?

Set the --fa-primary-color variable on :root for global changes or on a specific container for scoped theming. The default value is currentColor, which inherits from the parent text color. For layered icons, also set --fa-secondary-color to control the secondary layer.

Can I use Font Awesome 7 CSS custom properties with the Sass version?

Yes. The repository maintains parity between the CSS and Sass implementations. The file scss/_variables.scss contains the same values as the CSS custom properties, and scss/_functions.scss provides utilities to reference them during compilation.

What is the default value of --fa-width and how do I change it?

The default value is 1.25em. Override it by setting --fa-width: auto or any valid CSS length unit. When set to auto, icons expand to fit their content, which is useful for non-square icon applications or when using the .fa-width-auto utility class.

How do I customize the speed of Font Awesome 7 animations?

Override the --fa-animation-duration variable. The default is 1s. Apply it to a specific animation class like .fa-spin or globally on :root to affect all animated icons. Additional variables like --fa-beat-scale control the intensity of beat and bounce effects.

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