# Font Awesome 7 CSS Custom Properties for Theming: Complete Guide

> Explore Font Awesome 7 CSS custom properties to theme icons globally or per component. Customize font families, colors, sizing, and animations without modifying library source code.

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

---

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

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

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

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

```

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

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

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

```css
.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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss). The file [`scss/_functions.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss)**: SCSS source mirroring the CSS variables for Sass-based projects.
- **[`scss/_functions.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_functions.scss)**: Helper functions used by the SCSS build to reference variables.
- **[`css/fontawesome.css`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/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`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss) contains the same values as the CSS custom properties, and [`scss/_functions.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/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.