JavaScript Document fonts Property

What You’ll Learn

Document.fonts is an instance property that returns the document’s FontFaceSet—the heart of the CSS Font Loading API. Learn fonts.ready, status, checking and loading faces, adding a FontFace, and five examples with try-it labs.

Introduction

Web fonts declared with @font-face download in the background. Layout can shift when a custom face finally arrives. The CSS Font Loading API lets JavaScript wait for fonts, check whether a face is ready, and load fonts programmatically.

MDN: document.fonts returns the FontFaceSet of the document—useful for loading new fonts and checking the status of previously loaded fonts.

Related Document tutorials: firstElementChild, documentElement, Document constructor.

Understanding Document.fonts

An instance property on Document. Its value is the document’s FontFaceSet (MDN).

• Value — FontFaceSet for this document.
• Part of — CSS Font Loading API (MDN).
• Set-like — holds ordered FontFace objects; supports iteration / size.
• ready — Promise for when used fonts finish loading + layout (MDN).
• Workers — also available as self.fonts in workers (MDN FontFaceSet).

📝 Syntax

document.fonts

Value

The FontFaceSet interface of the document (MDN). Use it to load fonts and inspect loading status.

Common reads

document.fonts.status; // "loading" | "loaded"
document.fonts.size;   // number of FontFace entries
document.fonts.ready;  // Promise<FontFaceSet>

🔧 Useful FontFaceSet pieces

⚖️ Font loading approaches

Examples Gallery

Examples follow MDN Document: fonts and the FontFaceSet interface. Use View Output or Try It Yourself for each case.

document.fonts.ready.then((fontFaceSet) => {
  // Safe place for canvas text, measuring, etc.
  const fontFaces = [...fontFaceSet];
  console.log(fontFaces);
  // Some fonts may still be unloaded if unused (MDN)
  console.log(fontFaces.map((f) => f.status));
});

[FontFace, FontFace, ...]
["loaded", "loaded", ...]

console.log("status:", document.fonts.status);
console.log("size:", document.fonts.size);

document.fonts.ready.then(() => {
  console.log("after ready:", document.fonts.status);
});

status: loaded
size: 2
after ready: loaded

const ok = document.fonts.check("16px system-ui");
console.log("system-ui available?", ok);

const custom = document.fonts.check('16px "MyFancyFont"');
console.log("MyFancyFont available?", custom);

system-ui available? true
MyFancyFont available? false

document.fonts
  .load("16px system-ui")
  .then((faces) => {
    console.log("loaded count:", faces.length);
    console.log(faces.map((f) => f.family));
  })
  .catch((err) => console.error(err));

loaded count: 1
["system-ui"]

const face = new FontFace(
  "DemoFont",
  "url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2)"
);

face
  .load()
  .then((loaded) => {
    document.fonts.add(loaded);
    document.body.style.fontFamily = "DemoFont, system-ui, sans-serif";
    console.log("added:", loaded.family, loaded.status);
  })
  .catch((err) => console.error("Font failed:", err));

added: DemoFont loaded

🚀 Common Use Cases

• Canvas / SVG text — draw only after fonts.ready.
• Prevent layout thrash — measure headings once faces are loaded.
• Dynamic branding — load a partner font with FontFace + add.
• Feature gates — check() before enabling a typography-heavy UI.
• Debugging FOUT/FOIT — inspect status and each face’s status.
• Workers — use self.fonts where available for off-main-thread work.

📝 Notes

• MDN: Baseline Widely available (since January 2020) — no Deprecated / Experimental / Non-standard banner.
• Part of the CSS Font Loading API (MDN).
• ready tracks used fonts; unused faces may still be unloaded (MDN).
• delete / clear affect manually added faces; CSS-connected fonts stay (MDN).
• Related: firstElementChild, Document constructor.

💡 Best Practices