Gerillass 2.0.0 is out. It renames every utility function and replaces two mixins with one, so read the migration guide before you upgrade.

Gerillass

v2.3.0

Font Face

Type: Mixin
@include font-face();

* You can call mixins with or without the gls- namespace (e.g. @include gls-font-face();).

The Font Face Sass mixin helps you generate a cross-browser compatible @font-face declaration.

Arguments

NameTypeDescription
$font-familystringSets the name of the font-family. It cannot be a custom property: a @font-face rule drops font-family: var(--f), and without a family the font is never used. A quoted string is a name, so "var(--f)" in quotes is kept as one. The same rule drops an unquoted generic family or keyword such as sans-serif, serif, system-ui or inherit, and env() or attr(), so those are refused too. Quote the name if a font really is called that.
$file-pathstringSets the path and the name of the font file. The file name must be written without the extension. It cannot be a custom property: the path is written into url() as text.
$font-stylestringSets the font-style property. The default value is normal. If there is an italic version of the font, you can set the value to italic or oblique. A quoted value such as "italic" is written without its quotes, which a browser would drop. It cannot be a custom property.
$font-weightnumberSets the weight of the font. The default value is 400. Accepts 100, 200, 300, 400, 500, 600, 700, 800, and 900, or a range such as 160 700 for a variable font. A quoted value is written without its quotes. It cannot be a custom property, even as one end of a range: measured in Chrome 152, a @font-face rule dropped var() in font-family, font-style and font-weight.
$file-formatsstring | listSets the font file formats you want to include. The default value is eot woff2 woff ttf svg. A format outside that list is refused with an error. Pass only the formats you have files for: a bundler such as Parcel resolves every url() and fails on a missing file.
$font-displaystringSets the font-display descriptor, which decides what the text does while the font is still loading. Accepts auto, block, swap, fallback and optional. The default is null, which leaves it out, so the browser's own behaviour applies.

To learn more about the font-weight property values, check out the [links](#related-links) at the end of the article.

Examples

Let's call the mixin and pass values for the required arguments: $font-family and $file-path.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular");
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-regular.eot");
  src: url("fonts/fanwood-text/fanwood-text-regular.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-regular.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-regular.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-regular.ttf") format("truetype"), url("fonts/fanwood-text/fanwood-text-regular.svg#FanwoodText") format("svg");
  font-style: normal;
  font-weight: 400;
}

Now let's add the italic version of the family.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular", italic);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-regular.eot");
  src: url("fonts/fanwood-text/fanwood-text-regular.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-regular.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-regular.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-regular.ttf") format("truetype"), url("fonts/fanwood-text/fanwood-text-regular.svg#FanwoodText") format("svg");
  font-style: italic;
  font-weight: 400;
}

Now let's add the bold version of the Fanwood Text font-family (if there is one) by passing 700 for the $font-weight argument.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold", 700);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-bold.eot");
  src: url("fonts/fanwood-text/fanwood-text-bold.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-bold.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-bold.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-bold.ttf") format("truetype"), url("fonts/fanwood-text/fanwood-text-bold.svg#FanwoodText") format("svg");
  font-style: normal;
  font-weight: 700;
}

If you pass values for both the $font-style and $font-weight arguments, the $font-weight value should always come last, unless you also pass a value for $file-formats.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold-italic", italic, 700);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot");
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-bold-italic.ttf") format("truetype"), url("fonts/fanwood-text/fanwood-text-bold-italic.svg#FanwoodText") format("svg");
  font-style: italic;
  font-weight: 700;
}

Suppose you only have three file formats: woff2, woff, and ttf.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular", woff2 woff ttf);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-regular.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-regular.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-regular.ttf") format("truetype");
  font-style: normal;
  font-weight: 400;
}

If you want to pass values for all the arguments, the order must be $font-family, $file-path, $font-style, $font-weight, $file-formats, like in the example below.

Sass
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold-italic", italic, 700, woff2 woff);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff") format("woff");
  font-style: italic;
  font-weight: 700;
}

If you are having trouble passing the arguments by position, try named arguments.

Sass
@include font-face (
  $font-family: "Fanwood Text", 
  $file-path: "fonts/fanwood-text/fanwood-text-bold-italic",
  $font-style: italic, 
  $font-weight: 700,
  $file-formats: eot woff2 woff
);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot");
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff") format("woff");
  font-style: italic;
  font-weight: 700;
}

Try changing the order of the arguments. Whatever order you use, the result is the same.

Sass
@include font-face (
  $font-weight: 700,
  $font-style: italic,
  $file-formats: eot woff2 woff, 
  $font-family: "Fanwood Text",
  $file-path: "fonts/fanwood-text/fanwood-text-bold-italic",
);
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot");
  src: url("fonts/fanwood-text/fanwood-text-bold-italic.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-bold-italic.woff") format("woff");
  font-style: italic;
  font-weight: 700;
}

Now let's use the @content directive to pass a content block into the mixin.

Sass
@include font-face ("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular") {
  font-display: fallback;
}
CSS
@font-face {
  font-family: "Fanwood Text";
  src: url("fonts/fanwood-text/fanwood-text-regular.eot");
  src: url("fonts/fanwood-text/fanwood-text-regular.eot?#iefix") format("embedded-opentype"), url("fonts/fanwood-text/fanwood-text-regular.woff2") format("woff2"), url("fonts/fanwood-text/fanwood-text-regular.woff") format("woff"), url("fonts/fanwood-text/fanwood-text-regular.ttf") format("truetype"), url("fonts/fanwood-text/fanwood-text-regular.svg#FanwoodText") format("svg");
  font-style: normal;
  font-weight: 400;
  font-display: fallback;
}

If you don't have all the font varieties, or you have a font you want to convert into a web font (embeddable with @font-face), try Font Squirrel's Webfont Generator.

A variable font in one file. The weight range is written through as it is, and $font-display: swap shows the text in a fallback font until the file arrives, rather than hiding it.

Sass
@include font-face(
  "Readex Pro",
  "/fonts/readex-pro",
  $font-weight: 160 700,
  $file-formats: woff2,
  $font-display: swap
);
CSS
@font-face {
  font-family: "Readex Pro";
  src: url("/fonts/readex-pro.woff2") format("woff2");
  font-style: normal;
  font-weight: 160 700;
  font-display: swap;
}

Made with the loving music of Anna German and dedicated to James Williamson: The best web educator ever.