# Sass (SCSS)

Instructions for integrating Font Awesome icons into your Sass/SCSS workflow.

> Are you using Sass as a CSS preprocessor in your project? No problemo, Font Awesome has an SCSS version if you'd prefer to import our styling into your workflow.

We'll cover the basics of picking the SCSS files you'll need for your project, adding Font Awesome to your compile, inject code into a class with Mixins, and more.

Make sure you...

- [Downloaded the Font Awesome Web files](https://fontawesome.com/download) and have them handy.
- Have a project set up with [Sass](https://sass-lang.com).
- Need the power (variables, mixins, etc.) that SCSS brings. [Plain CSS](/web/setup/host-yourself/webfonts.md) is far less `<pun>`sass-y`</pun>`.

## Get Set Up

You'll find everything you need in the `scss` directory of the [Font Awesome download](https://fontawesome.com/download). Below is the list of files made specifically for SCSS. You can add them all to your project or pick just the ones you need.

| Files                          | What They Do                                                                                                                       |
| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `fontawesome.scss`             | Main Font Awesome compile                                                                                                          |
| `_animated.scss`               | [animated](/web/style/animate.md) icon support styling                                                                                |
| `_bordered.scss`               | [bordered](/web/style/pull.md) icon support styling                                                                                   |
| `_pulled.scss`                 | [pulled](/web/style/pull.md) icon support styling                                                                                     |
| `_core.scss`                   | Base icon reference class syntax and definition                                                                                    |
| `_widths.scss`                 | [Icon Canvas](/web/style/icon-canvas.md) width support styling                                                                        |
| `_icons.scss`                  | All icon definitions                                                                                                               |
| `_list.scss`                   | [icons in a list](/web/style/lists.md) support styling                                                                                |
| `_mixins.scss`                 | Utilities used throughout styling/icon definitions                                                                                 |
| `_rotated-flipped.scss`        | [rotating](/web/style/rotate.md) icons support styling                                                                                |
| `_sizing.scss`                 | [icon sizing](/web/style/size.md) support styling                                                                                     |
| `_stacked.scss`                | [stacking](/web/style/stack.md) icons support styling                                                                                 |
| `_variables.scss`              | Where variables are defined that are used throughout styling                                                                       |
| `_custom-icons.scss`           | includes custom icons in a [Kit Download](/web/setup/host-yourself/webfonts.md#hosting-your-own-downloaded-kit) (if you're using one) |
| Individual icon style partials | Support styling and configuration for each [icon style](/web/add-icons/how-to.md#families--styles)                                    |

  <h4>
    Compatibility

  </h4>

Font Awesome's SCSS can be compiled with [Sass](https://github.com/sass/sass)
and [Dart Sass](https://sass-lang.com/dart-sass). We tend to stick to the
latest versions of both compilers when possible.

Both [node-sass](https://github.com/sass/node-sass) and
[libsass](https://sass-lang.com/libsass) are [officially deprecated](https://sass-lang.com/blog/libsass-is-deprecated) and are not actively supported.

## Adding Font Awesome to Your Compile

Copy the `scss` folder into your project. Then copy the `webfonts` folder into your project, where your static files get served.

In your main SCSS compile file, you'll want to do the following things:

### Customize Font Awesome Variables

Any Font Awesome variable defined in the `_variables.scss` can be overriden when you load it using the [`@use`](https://sass-lang.com/documentation/at-rules/use) rule. You'll want to override the `$font-path` variable to point to where you placed the `webfonts` folder.

```scss
@use './fontawesome/variables' with (
  // customizing $font-path - make sure it points to where your webfonts are stored in your project
  $font-path: '../webfonts'
);
```

### Load Font Awesome's Core

Next, load Font Awesome's Core styling and make Font Awesome's helpers (mixins, functions, and variables) available via the `_fa.scss` partial which leverages Sass's [`@forward`](https://sass-lang.com/documentation/at-rules/forward) rule.

```scss
// customize variables
@use './fontawesome/variables' with (
  // customizing $font-path - make sure it points to where your webfonts are stored in your project
  $font-path: '../webfonts'
);

// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;
```

### Load Individual Styles

Each [icon style](/web/add-icons/how-to.md#families--styles) is available via an individual SCSS partial. Adds the files for the icon styles you plan to use in your project.

```scss
// customize variables
@use './fontawesome/variables' with (
  // customizing $font-path
  $font-path: '../webfonts'
);

// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// load individual Font Awesome styles - add only the ones you plan to use in your project. Here is an example of a project using Classic Solid, Brands, Duotone Solid, and Sharp Duotone Solid icons...
@use './fontawesome/solid' as fa-solid;
@use './fontawesome/brands' as fa-brands;
@use './fontawesome/duotone' as fa-duotone;
@use './fontawesome/sharp-duotone' as fa-sharp-duotone;
```

<h4>
  Namespacing + Font Awesome Sass

</h4>

Modern Sass practices recommend [using a namespace](https://sass-lang.com/documentation/at-rules/use/#choosing-a-namespace) with the `@use` rule. We recommend following our examples above and namespacing any loaded partials with `fa`. Whatever you choose, remember to reference it properly when calling variables, mixins, functions, etc.

<h4>
  Ch-chigity Check Your Paths!

</h4>

Make sure the font path and your `webfonts` directory are relative to where
your compiled CSS will be located.

## Adding Icons

Once you've added the imports above and have your compiled CSS that includes Font Awesome set up and [referenced in your project](/web/setup/host-yourself/webfonts.md), you can [add icons to your project's HTML](/web/add-icons/how-to.md).

Here's an example of how to reference icons with your compiled and hosted CSS:

```html
<head>
  <!--load your compiled CSS (including Font Awesome) -->
  <link href="/your-path-to-your-compiled-css-including-fontawesome/file.css" rel="stylesheet" />
</head>
<body>
  <!-- This example uses <i> element with:
  1. the `fa-solid` style class for solid style
  2. the `user` icon with the `fa-` prefix -->
  <i class="fa-solid fa-user"></i>

  <!-- Or you can use a <span> element, with classes applied in the same way -->

  <span class="fa-solid fa-user"></span>
</body>
```

<h4>
  SCSS Customizations at Your Command

</h4>

Any changes to the Font Awesome [SCSS
variables](#variables) (e.g. changing the `$css-prefix`
prefix variable or our [sizing scales](/web/style/size.md)), will take effect in your
project's compiled CSS.

## Writing Custom Sass/SCSS

If you are writing custom styling in the same file as your compile, you can use the namespaced `fa` partial to leverage the Font Awesome variables, mixins, and utilities like so:

```scss
// CASE: your main compile file

// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// the rest of your custom Sass/SCSS...
```

### In Partials

If you are writing custom styling in other [partials](https://sass-lang.com/documentation/at-rules/import/#partials) that your main compile is loading, you'll need to load the Font Awesome variables, mixins, and utilities yourself in the file that requires any of them.

```scss
// CASE: partial file that your main compile loads

// load  Font Awesome helpers (mixins, functions, and variables) as needed
@use './fontawesome/variables' as fa-v;
@use './fontawesome/mixins' as fa-m;
@use './fontawesome/functions' as fa-f;

// the rest of your partial's custom Sass/SCSS...
```

### Using Variables

Once loaded, you can use any of Font Awesome's [variables](#variables) in your custom rules.

  **Main Compile:**
  **Partial:**

```scss
// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// custom rules
.same-width-as-fa-icons {
  // using Font Awesome's fa-width variable to set the width of an element
  width: fa.$fw-width;
}
```

```scss
// load Font Awesome variables
@use './fontawesome/variables' as fa-v;

// custom rules
.same-width-as-fa-icons {
  // using Font Awesome's fa-width variable to set the width of an element
  width: fa-v.$fw-width;
}
```

### Using Mixins + Functions

Once loaded, you can use any of Font Awesome's [mixins](#mixins-and-functions) in your custom rules.

  **Main Compile:**
  **Partial:**

```scss
// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// custom rules
.size-same-as-xl-icon {
  // using Font Awesome's fa-size mixin to set the font-size of an element to the xl scale value
  @include fa.fa-size(xl);
}
```

```scss
// load Font Awesome variables and mixins
@use './fontawesome/variables' as fa-v; // needed because mixins use variables
@use './fontawesome/mixins' as fa-m;

// custom rules
.size-same-as-xl-icon {
  // using Font Awesome's fa-size mixin to set the font-size of an element to the xl scale value
  @include fa-m.fa-size(xl);
}
```

### Using Individual Style Mixins

One of the more common cases for writing custom Sass/SCSS is to handle [rendering icons using CSS pseudo-elements](/web/add-icons/pseudo-elements.md). This method is also useful when changing the HTML on your project is not an option.

Each [individual style you load](#load-individual-styles) into your project's compile includes a specific `icon()` mixin. These mixins handle the basic rendering that we bundle in our toolkit to make sure icons display perfectly. Along with that, they generate rules to render icon in the individual family + style.

Here's an example building off of previous code snippets:

```scss
// CASE: your main compile file

// customize variables
@use './fontawesome/variables' with (
  // customizing $font-path
  $font-path: '../webfonts'
);

// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// load individual Font Awesome styles
@use './fontawesome/solid' as fa-solid;
@use './fontawesome/regular' as fa-regular;
@use './fontawesome/light' as fa-light;
@use './fontawesome/thin' as fa-thin;
@use './fontawesome/duotone' as fa-duotone-solid;
@use './fontawesome/brands' as fa-brands;
@use './fontawesome/sharp-solid' as fa-sharp-solid;

// Solid style of user
.user {
  @include fa-solid.icon(fa.$var-user);
}

// Regular style of triangle-exclamation
.triangle-exclamation {
  @include fa-regular.icon(fa.$var-triangle-exclamation);
}

// Light style of newspaper
.newspaper {
  @include fa-light.icon(fa.$var-newspaper);
}

// Thin style of paintbrush-fine
.paintbrush-fine {
  @include fa-thin.icon(fa.$var-paintbrush-fine);
}

// Duotone style of camera-retro
.camera-retro {
  @include fa-duotone-solid.icon(fa.$var-paintbrush-fine);
}

// Sharp Solid style of trash
.trash {
  @include fa-sharp-solid.icon(fa.$var-trash);
}

// Bluesky brand icon
.bluesky {
  @include fa-brands.icon(fa.$var-bluesky);
}
```

---

## Using a Downloaded Kit

Did you know you can download a Kit to compile and host yourself just like you do with Font Awesome? To download your Kit, make sure the Kit's version is set to use v7 (or if you selected a specific version, it needs to be at least 6.4). Click the Download link on your Kit's page to see your download options. Your Kit download will contain all of the [SCSS files noted above](#get-set-up).

### Custom Icons in Downloaded Kits

If you have custom icons in your Kit, they will be included as an additional files in your Kit download.

| Path to the files                                                     | What the files do                                                                         |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| <span style="text-wrap: nowrap">`/webfonts/custom-icons.woff2`</span> | Custom icon font in WOFF2 format                                                          |
| `/scss/_custom-icons.scss`                                            | Sass (SCSS) Preprocessor partial that handles the display of custom icons using Web Fonts |

Here's a simple example that follows [the compile steps above](#adding-font-awesome-to-your-compile) along with custom icons:

```scss
// customize variables
@use './fontawesome/variables' with (
  // customizing $font-path
  $font-path: '../webfonts'
);

// load Font Awesome core
@use './fontawesome/fontawesome';

// load and make available Font Awesome helpers (mixins, functions, and variables)
@use './fontawesome/fa' as fa;

// load individual Font Awesome styles that you plan to use in your project
@use './fontawesome/solid' as fa-solid;
@use './fontawesome/brands' as fa-brands;
@use './fontawesome/duotone' as fa-duotone;
@use './fontawesome/sharp-duotone' as fa-sharp-duotone;

// load your custom icons
@use './fontawesome/custom-icons' as fa-custom-icons;
```

## Variables

Font Awesome's SCSS version also leverages several SCSS [variables](https://sass-lang.com/documentation/variables) that allow for easier set-up and customization of our styling toolkit.

| Variable                | What It Does                                                                                                                                                            |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$css-prefix`           | Sets the prefix (default set to `fa`) used on all styling toolkit CSS rules (e.g. `fa-lg`) + icon reference classes (e.g. `fa-user`)                                    |
| `$style`                | Sets the default icon style (using [`@font-face` weight](/web/add-icons/how-to.md#basics))                                                                                 |
| `$family`               | Sets the default `font-family` used                                                                                                                                     |
| `$display`              | Sets the [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/display) property (default set to `inline-block`) for rendered icons                              |
| `$font-display`         | Sets the [`font-display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) property for Font Awesome's icon fonts                              |
| `$fw-width`             | Sets the [`width`](https://developer.mozilla.org/en-US/docs/Web/CSS/width) property for all [fixed-width](/web/style/icon-canvas.md) icons                                 |
| `$inverse`              | Sets the [`color`](https://developer.mozilla.org/en-US/docs/Web/CSS/color) property of `.fa-inverse`                                                                    |
| `$border-box-sizing`    | Sets the [`box-sizing`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) property used in [bordered icons](/web/style/pull.md)                                 |
| `$border-color`         | Sets the [`border-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) property used in [bordered icons](/web/style/pull.md)                             |
| `$border-padding`       | Sets the [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) property used in [bordered icons](/web/style/pull.md)                                       |
| `$border-radius`        | Sets the [`border-radius`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) property used in [bordered icons](/web/style/pull.md)                           |
| `$border-style`         | Sets the [`border-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style) property used in [bordered icons](/web/style/pull.md)                             |
| `$border-width`         | Sets the [`border-width`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) property used in [bordered icons](/web/style/pull.md)                             |
| `$li-width`             | Sets the [`width`](https://developer.mozilla.org/en-US/docs/Web/CSS/width) property for `fa-li` elements when styling [icons in a list](/web/style/lists.md) icons         |
| `$li-margin`            | Sets the [`margin-right`](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) property for `fa-li` elements when styling [icons in a list](/web/style/lists.md) icons |
| `$pull-margin`          | Sets the [`margin-left`/`margin-right`](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) property for [pulled icons](/web/style/pull.md) icons                     |
| `$primary-opacity`      | Sets the [opacity](https://developer.mozilla.org/en-US/docs/Web/CSS/opacity) of a [duotone](/web/style/duotone.md) icon's primary layer                                    |
| `$secondary-opacity`    | Sets the [opacity](https://developer.mozilla.org/en-US/docs/Web/CSS/opacity) of a [duotone](/web/style/duotone.md) icon's secondary layer                                  |
| `$size-scale-base`      | Sets the base step size that all other [relative sizing](/web/style/size.md#relative-sizing) steps are based on                                                            |
| `$size-scale-2xs`       | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-2xs`                                                               |
| `$size-scale-xs`        | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-xs`                                                                |
| `$size-scale-sm`        | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-sm`                                                                |
| `$size-scale-lg`        | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-lg`                                                                |
| `$size-scale-xl`        | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-xl`                                                                |
| `$size-scale-2xl`       | Sets the size of step used when [relatively sizing icons](/web/style/size.md#relative-sizing) with `.fa-2xl`                                                               |
| `$stack-vertical-align` | Sets the [vertical-align](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align) property of [stacked icons](/web/style/stack.md)                                |
| `$stack-width`          | Sets the [width](https://developer.mozilla.org/en-US/docs/Web/CSS/width) property of [stacked icons](/web/style/stack.md)                                                  |
| `$stack-z-index`        | Sets the [z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index) property of [stacked icons](/web/style/stack.md)                                              |
| `$font-path`            | Sets the location of Font Awesome's webfonts folder and assets.                                                                                                         |

## Mixins and Functions

Font Awesome's SCSS leverages a small amount of [mixins](https://sass-lang.com/documentation/at-rules/mixin/) and [functions](https://sass-lang.com/documentation/at-rules/function/) to help render icons.

| Utility                                                                            | What It Does                                                                                                                                                                     | Arguments                                                                                                       |
| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `fa-icon()`                                                                        | Produces all of the base style set up for an icon's rendering, plus configuration for a specific [icon family and style](#load-individual-styles)                                | `$family` &mdash; any valid [`font-family`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) value |
| `fa-size()`                                                                        | Relatively adjusts the size of an icon using Font Awesome's [relative sizing](/web/style/size.md#relative-sizing) styling and scale                                                 | `$font-size` &mdash; any valid size value from [the relative sizing scale](/web/style/size.md#relative-sizing)     |
| `fa-content()`                                                                     | A [function](https://sass-lang.com/documentation/at-rules/function) to make referencing icons via the CSS `content` property a bit easier                                        | `$var` &mdash; Any valid icon-based variable (e.g. `fa-content($fa-var-user);`)                                 |
| `icon()` found in [individual icon style partials](#using-individual-style-mixins) | Individual Style-only mixins that produce all the base style set up for an icon's rendering, plus configuration for a specific [icon family and style](#load-individual-styles). | **N/A** - family and style are set explicitly with these                                                        |