Skip to main content

no-invalid-font-display

Disallow invalid font-display descriptor values in @font-face blocks.

Rule catalog ID: R037

Targeted pattern scopeโ€‹

  • font-display declarations inside @font-face blocks.

What this rule reportsโ€‹

This rule reports font-display values that are not valid CSS Fonts descriptors.

Valid values are:

  • auto
  • block
  • swap
  • fallback
  • optional

Why this rule existsโ€‹

Invalid font-display values are ignored by browsers, which silently falls back to default behavior. That often causes inconsistent rendering strategy (FOIT/FOUT behavior) compared with project expectations.

Because this failure mode is silent at runtime, a dedicated lint rule catches mistakes earlier than visual QA.

โŒ Incorrectโ€‹

@font-face {
  font-family: "Inter";
  font-display: fast;
  src: url("./inter.woff2") format("woff2");
}
@font-face {
  font-family: "Inter";
  font-display: swapy;
  src: url("./inter.woff2") format("woff2");
}

โœ… Correctโ€‹

@font-face {
  font-family: "Inter";
  font-display: swap;
  src: url("./inter.woff2") format("woff2");
}
@font-face {
  font-family: "Inter";
  font-display: optional;
  src: url("./inter.woff2") format("woff2");
}

Stylelint config exampleโ€‹

import fontPlugin, { fontPluginConfigs } from "stylelint-plugin-font";

export default {
  ...fontPluginConfigs["font-recommended"],
  plugins: [...fontPlugin],
  rules: {
    ...fontPluginConfigs["font-recommended"].rules,
    "font/no-invalid-font-display": true,
  },
};

When not to use itโ€‹

Disable this rule only if your stylesheets intentionally include non-standard custom-syntax tokens in font-display and a downstream transform rewrites them before they reach browsers.

Further readingโ€‹