This rule raises an issue when an @font-face rule loads a font from a URL and its font-display descriptor is missing,
auto, or block. With block, and with auto in many browsers, the browser hides the text for a short
period while the font downloads, so visitors cannot read it. Use one of the following values instead, so that the text stays readable in a fallback
font while the font loads:
swap: shows the fallback font almost immediately and switches to the downloaded font when it arrives. The layout can shift when the
font changes. Use it for short text, such as a logo, where the font matters.fallback: shows the fallback font almost immediately and switches only if the downloaded font arrives shortly after. Use it for
body text.optional: uses the downloaded font only if it is available almost immediately, and otherwise keeps the fallback font. Use it for
fonts that are not essential.
@font-face { /* Noncompliant: "font-display" is missing */
font-family: "BodyText";
src: url("body.woff2") format("woff2");
}
@font-face {
font-family: "BodyText";
src: url("body.woff2") format("woff2");
font-display: fallback;
}
An explicit auto or block value is reported on the font-display declaration:
@font-face {
font-family: "BrandLogo";
src: url("logo.woff2") format("woff2");
font-display: block; /* Noncompliant: "block" can hide text while the font loads */
}
@font-face {
font-family: "BrandLogo";
src: url("logo.woff2") format("woff2");
font-display: swap;
}
The rule does not report an @font-face rule when:
src descriptor uses only local() sources or data: URLs. Such fonts do not wait for a network request.
When src is declared several times, only the last declaration counts, as in the browser.font-display uses a value set through a variable, such as var(--font-display), or an invalid value.@include in SCSS and Less, because such
statements may add descriptors that the rule cannot see.ignoreFontFamilies parameter.For example, this font is not reported because it does not download anything:
@font-face {
font-family: "BodyText";
src: local("Body Text"), local("BodyText-Regular");
}
An @font-face rule that lists a local() source before a url() source is still reported, because the browser
downloads the font when it is not installed.
Use ignoreFontFamilies for icon and glyph fonts, which the rule cannot tell apart from text fonts. They usually keep
block, so that the fallback font’s text, such as raw ligature names, does not appear before the icons load. Each value is a family name,
compared without regard to case, or a regular expression written as /pattern/. The parameter is empty by default.
font-display
valuesfont-display