Why is this an issue?

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:

Code examples

Noncompliant code example

@font-face { /* Noncompliant: "font-display" is missing */
  font-family: "BodyText";
  src: url("body.woff2") format("woff2");
}

Compliant solution

@font-face {
  font-family: "BodyText";
  src: url("body.woff2") format("woff2");
  font-display: fallback;
}

Noncompliant code example

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 */
}

Compliant solution

@font-face {
  font-family: "BrandLogo";
  src: url("logo.woff2") format("woff2");
  font-display: swap;
}

Exceptions

The rule does not report an @font-face rule when:

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.

Resources

Documentation