oxc-project/oxc · warning · OxcDiagnostic

A font-display parameter is missing (adding `&display=option

Error message

A font-display parameter is missing (adding `&display=optional` is recommended).

What it means

This is the `nextjs/google-font-display` rule in oxlint. It fires when a `<link>` whose `href` starts with `https://fonts.googleapis.com/css` has no `display` query parameter. Without `display=`, the Google Fonts CSS defaults to `font-display: auto`/block behavior, risking invisible text (FOIT) and layout shift during font loading; `optional` avoids both.

Source

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

use oxc_ast::{AstKind, ast::JSXElementName};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
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
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Append `&display=optional` (recommended) to the Google Fonts CSS URL.
2. If swapping in the font after load matters visually, use `&display=swap` (also passes this rule).
3. Better: switch to `next/font/google`, which handles font-display and self-hosting automatically.

Example fix

// before
<link href="https://fonts.googleapis.com/css2?family=Krona+One" rel="stylesheet" />

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

npx oxlint --nextjs/google-font-display src/ # or: rg -n 'fonts\.googleapis\.com/css[^"']*"\s' --glob '*.tsx' -P '(?<!display=[a-z]+)' src/

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

When it happens

Trigger: A JSX `<link>` element with a string-literal `href` beginning with `https://fonts.googleapis.com/css` where `find_url_query_value(href, "display")` returns None — e.g. `href="https://fonts.googleapis.com/css2?family=Krona+One"` inside `next/head` or `next/document`.

Common situations: Adding Google Fonts via raw `<link>` tags instead of `next/font`; copying font snippets from Google Fonts' UI (which defaults to no display or `display=swap`); App Router/Docs examples pasted without the display param; CI lint gates failing on new font integrations.

Related errors

• `{font_display_value}` is not a recommended font-display val
• `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/ddd8065e6ca121ff. Report an issue: GitHub.