# Faces Mixin [#faces-mixin]

The font faces mixin allows you to generate a highly customizable CSS file for your font by modifying various [`@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) variables. This guide explains how to use the Faces mixin in your Sass/SCSS projects.

## Installation [#installation]

To use the Faces mixin, you must install the `@fontsource-utils/scss` helper package and the specific font package you want to customize:

```sh
npm install @fontsource-utils/scss
yarn add @fontsource-utils/scss
pnpm add @fontsource-utils/scss
bun add @fontsource-utils/scss
```

Then, import the Fontsource mixins in your Sass/SCSS file using the `@use` rule:

```scss
@use "pkg:@fontsource-utils/scss" as fontsource;
@use "pkg:@fontsource-variable/recursive/scss" as recursive;
```

## Usage [#usage]

Once you have imported the mixin, you can use it to generate a CSS file with customized font variations. Here’s an example that generates a CSS file similar to `recursive/latin-500-italic.css`:

```scss
@include fontsource.faces(
  $metadata: recursive.$metadata,
  $subsets: latin,
  $weights: 500,
  $styles: italic
);
```

You can customize the font variations by specifying different subsets, weights, and styles. Use the all option if you want to include all available options for a specific property. Here’s an example that includes multiple subsets, weights, and all available styles:

```scss
@include fontsource.faces(
  $metadata: recursive.$metadata,
  $subsets: (
    latin,
    greek,
  ),
  $weights: (
    300,
    400,
    800,
  ),
  $styles: all
);
```

### Mixin Arguments [#mixin-arguments]

The Faces mixin accepts several properties as arguments, allowing you to customize various aspects of the font. Here are the available arguments::

| Variable | Description                                                                                                                                       | Options                                                                         | Default                                  |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- |
| $family  | Font family name (see [font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family))                                     | Any string                                                                      | Metadata default used (e.g. “Open Sans”) |
| $display | How the font is displayed when loading (see [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display))             | One of: `auto`, `block`, `swap`, `fallback`, `optional`                         | `swap`                                   |
| $formats | List of included font file formats (see [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src))                                   | `all`, or any of: `woff`, `woff2`                                               | `all`                                    |
| $subsets | List of included subsets                                                                                                                          | `all`, or any of the subsets listed for the font                                | Metadata default used (e.g. latin)       |
| $weights | List of included weights (see [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight))                             | `all`, or any of the weights listed for the font                                | Metadata default used (e.g. 400)         |
| $styles  | List of included styles (see [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style))                                | `all`, or any of the styles listed for the font (usually `normal` and `italic`) | Metadata default used (e.g. normal)      |
| $axes    | List of included variable font axes (see [Variable fonts guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide)) | `all` (which uses `full`), or any of the axes listed for the font               | `full`                                   |

The following advanced properties shouldn’t need to be modified as often, but are still available for use:

| Variable   | Description                                                                                                                                                                                       | Default                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| $metadata  | [Metadata map](https://github.com/fontsource/font-files/blob/main/fonts/google/open-sans/scss/metadata.scss), which is used for resolving default options, available properties, and source paths | Default package metadata (located in `scss/metadata.scss`) |
| $directory | Base directory used for the font source paths                                                                                                                                                     | Default package path (e.g. `~@fontsource/open-sans/files`) |

### Global Configuration [#global-configuration]

The arguments for the Faces mixin can also be set directly on module import, which will set the new defaults throughout different uses of the mixin. Here’s an example:

```scss
@use "@fontsource-utils/scss" as fontsource with (
  $weights: (
    300,
    700,
  ),
  $family: "Fontsource Custom"
);

@include fontsource.faces(
  $metadata: recursive.$metadata
  // The global configuration can still be overwritten through arguments
  $family: "Recursive Other"
);
```

By setting the arguments on module import, you can easily configure the defaults for the Faces mixin.