how to preload only some font weights with next/font

[stefanprobst]

Summary

i want to preload font-weight 400 of a local font, but not preload additional font-weights, using next/font. what is the recommended approach to do that? or is the nextjs team thinking of adding support for this?

the only hint i found was this comment, which relies on behavior that is not documented and hard to discover (and the font-family declaration override must be named like the exported binding, otherwise the css custom property is wrong).

Additional information

No response

Example

No response

[CedricConday]

preload is per loader call, not per weight — one boolean for whatever that call declares. So the supported way to get this is two calls:

const bodyFont = localFont({ src: './MyFont-Regular.woff2', weight: '400', variable: '--font-body' })
const boldFont = localFont({ src: './MyFont-Bold.woff2', weight: '700', preload: false, variable: '--font-bold' })

The docs are explicit that each call is its own hosted instance, which is what makes the preload decision independent.

The catch is the one you already found: two calls mean two families, so weight-based selection inside one family is what needs the declarations override. That part is undocumented, and worth an issue on its own rather than folding into this one.

[Dani-8]

@stefanprobst Cedric is spot on—next/font/local evaluates preload per loader call, so splitting the font configurations into two separate localFont calls is the official way to control preloading per weight.

If you want to avoid manually overriding @font-face or font-family declarations to combine them under one family name, you can cleanly unify both weights using CSS variables in your layout or root stylesheet:

1. Define the fonts separately in your layout.tsx or config:

import localFont from 'next/font/local'

export const regularFont = localFont({
  src: './MyFont-Regular.woff2',
  weight: '400',
  preload: true, // Preloaded
  variable: '--font-regular',
})

export const boldFont = localFont({
  src: './MyFont-Bold.woff2',
  weight: '700',
  preload: false, // Not preloaded
  variable: '--font-bold',
})

2. Apply both variable class names to / :

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${regularFont.variable} ${boldFont.variable}`}>
      <body>{children}</body>
    </html>
  )
}

3. Assign them in CSS / Tailwind:
   In CSS:

body {
  font-family: var(--font-regular), sans-serif;
}

strong, b, .font-bold {
  font-family: var(--font-bold), sans-serif;
}

Or in tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['var(--font-regular)', 'sans-serif'],
        bold: ['var(--font-bold)', 'sans-serif'],
      },
    },
  },
}

This keeps the preloading behavior explicit while avoiding fragile or undocumented font-family override hacks.

[icyJoseph]

Hi @stefanprobst thanks for the call out, I'll investigate a bit more, get some agents to poke around some apps, and do the necessary docs updates, but I think there might be a feature gap still. I think #69900 tried to address that no?

As far as I can tell the other answers are non-starters right?

[stefanprobst]

I'll investigate a bit more

thanks!

there might be a feature gap still

yes i think so too - #69900 does look promising indeed.

the other answers are non-starters right

yep, i am looking for a single font-family name and css custom property, but different preload behavior per font-weight.

[icyJoseph]

Been trying this out, I don't really feel comfortable documenting the pattern — as far as I can see, indeed, declarations does the trick:

// app/fonts.ts
import localFont from "next/font/local";

// Both calls write the same font-family, so the browser sees one family.
// Only this one is preloaded.
export const myFont = localFont({
  src: "./fonts/regular.woff2",
  weight: "400",
  variable: "--my-font",
  declarations: [{ prop: "font-family", value: "myFont" }],
});

// Same family, not preloaded. Importing it is enough; you never use its return value.
const myFontDeferred = localFont({
  src: "./fonts/bold.woff2",
  weight: "700",
  preload: false,
  adjustFontFallback: false,
  declarations: [{ prop: "font-family", value: "myFont" }],
});

I can see how this is also problematic, in the test I have there's flash of un-styled text, while the bold text loads. This is not a property of the hack/workaround though just about not preloading the font.

It is also very fragile, a unused const and if you rename the const binding myFont, to theFont, without updating the declaration value, you'd end with --my-font: theFont, but the css rule font family is myFont, the className would also have theFont in the css declaration for font-family.

If I were to document the pattern, I'd also include an e2e to ensure it doesn't silently regress. I can make the preload and declarations slightly better though, I think.

[stefanprobst]

thanks for trying this out! - tbh i would not document this pattern, it feels very brittle - i'd rather next/font add dedicated api for this usecase.

[icyJoseph]

Right, for some reason I am reading it as a rather advance use case. Like I said it is very easy to get yourself into flash of un-styled text, and that can have some nasty consequences.

I wonder if something like this is a better fit https://react.dev/reference/react/Suspense#waiting-for-a-font-to-load

[icyJoseph]

Rough... none of my comments here's really an resolution type of answer, but it is the current state of things. Bots are spamming the same variation of the same workaround 😞 — which has been stablished in the OP to be unwanted, and trivially obvious... could we agree that:

• how to preload only some font weights with `next/font` #99025 (reply in thread)

Is probably a fair answer right now?

[stefanprobst]

👍 i marked it as answer - i'd still wish for something like #69900 to land (i can send a pr if there's a chance for it to go in)

[gilangabdian]

I think the feature gap is real here.

preload is currently configured on the localFont() call, while multiple weights can be defined inside the same src array. So there isn't a documented API that lets you do something like:

localFont({
  src: [
    { path: './Regular.woff2', weight: '400', preload: true },
    { path: './Bold.woff2', weight: '700', preload: false },
  ],
})

Splitting the weights into two localFont() calls does give independent preload control, but it also creates separate font instances/family handling, which doesn't really satisfy the requirement of one family name.

The declarations approach with two calls and the same font-family can work as a workaround, but I would treat it as a workaround rather than the clean API for this use case. The current documentation describes declarations as modifying the generated @font-face, but it doesn't document using it to merge separate loader calls into one family. ref

So for the specific requirement of one font family + one CSS variable + different preload behavior per weight, I don't think there is currently a clean, documented next/font solution.

This is essentially the use case discussed in #46699, which proposes selective preload per local font source.

I'd keep an eye on #69900 as well, since it appears related to this gap.

References:

• Related PR: feat(next/font): Add font format fallback and declarations per font path #69900

[Icyubahiro-Jay-P]

Currently preload is set per localFont() call, not per weight inside a single call, and there is no official documented way to keep one font-family plus one CSS variable while preloading only some weights. The cleanest supported approach is two separate localFont calls: one for the regular weight with preload true and one for the bold weight with preload false, each exporting its own CSS variable. Apply both variables on the root html element and then map them in CSS or Tailwind so body uses the regular variable and .font-bold / strong / b use the bold variable. This keeps the preload behavior explicit and avoids fragile undocumented hacks. There is still a real feature gap here (also discussed in #46699); until Next.js adds a proper API for selective preloading per weight, the two-call pattern is the least brittle option.

[michel-brotherhood]

I found PR #69900, which proposes preload per font source inside src[]. That seems closely related to this use case. Since the PR is still open, has anyone tested whether this approach is still being considered or whether there is a newer supported API?

[delt4-haze]

To control preloading for specific font weights using next/font, you can split the font definitions into separate loader calls:

1. Preloaded weight: Set preload: true for weight 400.
2. Non-preloaded weights: Set preload: false for the additional weights.

Here is the recommended setup:

import localFont from 'next/font/local';

export const mainFont400 = localFont({
  src: './fonts/my-font-400.woff2',
  weight: '400',
  preload: true,
  variable: '--font-main-400',
});

export const mainFont700 = localFont({
  src: './fonts/my-font-700.woff2',
  weight: '700',
  preload: false,
  variable: '--font-main-700',
});


Then apply both CSS variables to your `<html>` or `<body>` element so both weights are accessible while only preloading the primary one

```tsx
<html className={`${mainFont400.variable} ${mainFont700.variable}`}>

[icyJoseph]

OP has already stablished that this is not their goal. It is a trivial, obvious approach.

yep, i am looking for a single font-family name and css custom property, but different preload behavior per font-weight.

[DYNOSuprovo]

To preload only specific weights (e.g., 400) while loading additional weights (e.g., 700) on demand without preloading, you can define separate font instances using next/font/local:

// app/fonts.ts
import localFont from 'next/font/local';

// 1. Regular font - preloaded by default
export const fontRegular = localFont({
  src: './fonts/CustomFont-Regular.woff2',
  weight: '400',
  preload: true,
  variable: '--font-regular',
  display: 'swap',
});

// 2. Bold font - preloading disabled
export const fontBold = localFont({
  src: './fonts/CustomFont-Bold.woff2',
  weight: '700',
  preload: false,
  variable: '--font-bold',
  display: 'swap',
});

In your root layout:

import { fontRegular, fontBold } from './fonts';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${fontRegular.variable} ${fontBold.variable}`}>
      <body>{children}</body>
    </html>
  );
}

By separating the definitions, Next.js will only inject <link rel="preload"> tags for fontRegular, keeping your initial page payload minimal while still allowing fontBold to be utilized via CSS variables.

Hope this helps! If this resolves your question, please feel free to mark this as the accepted answer.

[Icaro0310]

I wouldn't rely on that comment. In current next/font, preload is per loader call, not per src entry, so a multi-weight src array is all or nothing.

What I do is split the critical weight from the rest:

const inter400 = localFont({ src: '../fonts/inter-400.woff2', variable: '--font-inter' })
const interRest = localFont({
 src: [
 { path: '../fonts/inter-500.woff2', weight: '500' }
 { path: '../fonts/inter-700.woff2', weight: '700' }
 ]
 preload: false
})

Use inter400.variable globally and apply interRest.className where 500/700 are actually needed. If font-weight: 700 must resolve under the exact same family name, there isn't a documented switch today.

—
Related work of mine: github.com/Icaro0310 · Website: icaro0310.github.io

[MUXAB18]

A workaround is to split the regular font face into its own localFont() call and disable preloading for the remaining weights. Both calls can use the same explicit font-family declaration through declarations:

// fonts.ts
import localFont from "next/font/local";

export const myFont = localFont({
  src: "./fonts/myfont-regular.woff2",
  variable: "--font-myfont",
  preload: true,
  declarations: [{ prop: "font-family", value: "MyFont" }],
});

export const myFontOtherWeights = localFont({
  src: [
    { path: "./fonts/myfont-medium.woff2", weight: "500" },
    { path: "./fonts/myfont-bold.woff2", weight: "700" },
  ],
  variable: "--font-myfont-other",
  preload: false,
  adjustFontFallback: false,
  declarations: [{ prop: "font-family", value: "MyFont" }],
});

Apply both generated variable classes in the root layout:

<html
  className={`${myFont.variable} ${myFontOtherWeights.variable}`}
>

Because both calls declare the same font-family, the browser can match the correct face by weight without needing separate CSS family overrides. Only the regular font call is configured for preloading.

This appears to work with Next.js 16.2.11 and Turbopack, as reported in this discussion, but I would verify the generated CSS and preload links for the specific Next.js version in use.

A native per-source preload option would still be a cleaner and more discoverable API.