oxc-project/oxc · warning · OxcDiagnostic

`{font_display_value}` is not a recommended font-display val

Error message

`{font_display_value}` is not a recommended font-display value.

What it means

This is the `nextjs/google-font-display` rule in oxlint, second diagnostic (constructor `not_recommended_font_display_value` at crates/oxc_linter/src/rules/nextjs/google_font_display.rs:21). It fires when the `display` query parameter of a Google Fonts CSS URL is `auto`, `block`, or `fallback` (the exact match list in `run()`). These strategies allow text to be invisible or cause layout shift, unlike `optional` and `swap` which the rule accepts.

Source

Thrown at crates/oxc_linter/src/rules/nextjs/google_font_display.rs:22

use oxc_span::{GetSpan, Span};

use crate::{
    AstNode,
    context::LintContext,
    rule::Rule,
    utils::{find_url_query_value, get_string_literal_prop_value, has_jsx_prop_ignore_case},
};

fn font_display_parameter_missing(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(
        "A font-display parameter is missing (adding `&display=optional` is recommended).",
    )
    .with_help("See https://nextjs.org/docs/messages/google-font-display")
    .with_label(span)
}

fn not_recommended_font_display_value(span: Span, font_display_value: &str) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!("`{font_display_value}` is not a recommended font-display value."))
        .with_help("See https://nextjs.org/docs/messages/google-font-display")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct GoogleFontDisplay;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Enforce font-display behavior with Google Fonts.
    ///
    /// ### Why is this bad?
    ///
    /// Specifying display=optional minimizes the risk of invisible text or
    /// layout shift. If swapping to the custom font after it has loaded is
    /// important to you, then use `display=swap`` instead.
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Change the value to `optional` (best for no layout shift) or `swap` (if the swap flash is acceptable).
2. Migrate to `next/font/google` with `display: 'optional'` | `'swap'` in the options object.
3. Remove the parameter only if you then intentionally accept the missing-display diagnostic — otherwise pick a passing value.

Example fix

// before
<link href="https://fonts.googleapis.com/css2?family=Inter&display=block" rel="stylesheet" />

// after
<link href="https://fonts.googleapis.com/css2?family=Inter&display=optional" rel="stylesheet" />

npx oxlint --nextjs/google-font-display src/

const isRecommendedDisplay = (href: string) =>
  /[?&]display=(optional|swap)(&|$)/.test(href);

When it happens

Trigger: A `<link>` with string-literal `href` starting `https://fonts.googleapis.com/css` whose `display` query value equals `auto`, `block`, or `fallback` — e.g. `href="...&display=block"`. The diagnostic label points at the href prop span.

Common situations: Copying the embed snippet from Google Fonts with `display=auto` defaults; choosing `block` to guarantee the custom font renders (at the cost of invisible text); retrofitting `display=fallback` after hearing about FOIT without understanding the tradeoff.

Related errors

• A font-display parameter is missing (adding `&display=option
• `rel="preconnect"` is missing from Google Font.
• Custom fonts not added in `pages/_document.js` will only loa
• Do not use `<a>` elements to navigate between Next.js pages.
• Using `<img>` could result in slower LCP and higher bandwidt

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/d32954d9f7e3e8d5. Report an issue: GitHub.