Faces Mixin

The font faces mixin allows you to generate a highly customizable CSS file for your font by modifying various @font-face variables. This guide explains how to use the Faces mixin in your Sass/SCSS projects.

Installation

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

⬤⬤

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:

⬤⬤

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

scss

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:

⬤⬤

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

scss

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:

⬤⬤

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

scss

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)	Any string	Metadata default used (e.g. “Open Sans”)
$display	How the font is displayed when loading (see font-display)	One of: `auto`, `block`, `swap`, `fallback`, `optional`	`swap`
$formats	List of included font file formats (see 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)	`all`, or any of the weights listed for the font	Metadata default used (e.g. 400)
$styles	List of included styles (see 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)	`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, 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

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:

⬤⬤

@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"
);

scss

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