Gerillass 3.0.0 is out. One gradient mixin replaces two, and text-gradient takes its colours first, so read the migration guide before you upgrade.
Gerillass
v3.0.0* 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.
Important: The mixin must be called at the root level of your stylesheet.
Arguments
| Name | Type | Description |
|---|---|---|
$font-family | string | Sets 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-path | string | Sets 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-style | string | Sets 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, and oblique takes one or two angles between -90deg and 90deg, such as oblique 10deg 20deg. auto works too. A number here is read as the weight. A quoted value such as "italic" is written without its quotes, which a browser would drop. It cannot be a custom property. |
$font-weight | number | Sets the weight of the font. The default value is 400. Accepts normal, bold, auto, any number from 1 to 1000, such as 700 or 450, or a range such as 160 700 for a variable font. bolder, lighter and the CSS-wide keywords are refused, because a @font-face rule drops them. 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-formats | string | list | Sets 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-display | string | Sets 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.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular");@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.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular", italic);@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.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold", 700);@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.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold-italic", italic, 700);@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;
}Things get trickier when you want to pass a value for $file-formats. The examples below show the ways to do it.
Suppose you only have three file formats: woff2, woff, and ttf.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular", woff2 woff ttf);@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.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-bold-italic", italic, 700, woff2 woff);@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;
}Tip: Do you know what is beautiful about named arguments? They are order-independent, which makes them very useful when it is hard to stick to the argument order.
If you are having trouble passing the arguments by position, try named arguments.
@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
);@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.
@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",
);@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.
@include font-face ("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular") {
font-display: fallback;
}@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.
@include font-face(
"Readex Pro",
"/fonts/readex-pro",
$font-weight: 160 700,
$file-formats: woff2,
$font-display: swap
);@font-face {
font-family: "Readex Pro";
src: url("/fonts/readex-pro.woff2") format("woff2");
font-style: normal;
font-weight: 160 700;
font-display: swap;
}What it refuses
A style or a weight that a @font-face rule drops stops the build. Measured in Chrome 152 by inserting the rule and reading it back, the rule keeps the values listed under Arguments and drops the rest, such as bolder, inherit, 0 or an oblique angle past 90 degrees. Until 2.3.1 they compiled, and the font was then matched with the browser's default for that descriptor instead.
@include font-face("Fanwood Text", "fonts/fanwood-text/fanwood-text-regular", $font-weight: bolder);Error: `bolder` is not a valid $font-weight for `font-face`: a weight is normal, bold, auto or a number from 1 to 1000; bolder, lighter and the CSS-wide keywords are dropped. A @font-face rule drops the descriptor.A weight passed in the style's place is read as the weight. That used to work only for the hundreds, so font-face("Fanwood Text", "...", 450) wrote font-style: 450; it now writes font-weight: 450.
A quoted number is checked for its shape and not its range, because Sass cannot turn the text of a number into one: $font-weight: "1001" is let through.