Font loading and substitution

A name in the font toolbar does not mean the browser has that font. Missing fonts affect widths, wrapping and pagination. Choose explicit sources and distinguish saved font intent from what this device can render.

Option one: application-mounted fonts

For a fixed brand font or offline deployment, declare an accessible @font-face in application CSS, wait for loading, then disclose its exact CSS family through mountedFamilies. Application Serif is an example name, not a bundled font; replace it with your actual face.

import type { ClassicEditorWebFontOptions } from "@quirekit/classic-editor";

/**
 * Waits for an application-owned @font-face before creating Classic.
 * @param owner - Browser document whose stylesheet already declares the face.
 * @returns Explicit mounted-family configuration without an external catalog.
 */
export async function prepareApplicationFonts(owner: Document): Promise<ClassicEditorWebFontOptions> {
  const faces = await owner.fonts.load('16px "Application Serif"');
  if (faces.length === 0) throw new Error("Application Serif has no registered @font-face.");
  return { families: [], catalogs: [], mountedFamilies: [{ family: "Application Serif", displayName: "应用正文字体" }] };
}

const webFonts = await prepareApplicationFonts(host.ownerDocument)
const instance = createClassicEditor({ element: host, preset, document, webFonts })

Use the host, Word preset and content from the quick start. mountedFamilies does not load CSS. webFonts: false neither loads missing fonts nor eliminates font differences.

displayName labels a family; it cannot replace its exact family. Configuring a source does not change content's font choice. Use installed setFontFamily(family) for the current selection. The document font theme belongs to canonical document configuration.

Option two: install external fonts on demand

webFonts accepts families, catalogs and searchable sources. Families disclose installable metadata. Catalogs resolve exact family names into complete manifests; sources provide search, paging and manifest resolution. A manifest includes version, faces, assets and license information, rather than just a display name or stylesheet URL.

After mounting, read instance.fontLibrary. Subscribe to changes, then call install(family) after an explicit user action. Its Promise completes after browser registration and layout invalidation. previewFamily() previews without adding an imported-family record; importFamily() manages explicit import. Unsubscribe on exit/library replacement and recheck instance ownership after asynchronous work.

Supplying your own families/catalogs replaces the default configuration; do not assume default sources remain. Control resource budgets through maxAssetBytes, maxConcurrentAssets, fetch and cache.

Understand font status

instance.documentFontStatus describes the document body font:

Do not silently rewrite content's family when substituting. Scripts and individual missing glyphs can still use glyph fallback, so one body-font status does not establish identical rendering throughout the document.

Verify layout and export

Built-in installation refreshes font metrics and layout. If your application loads CSS fonts after mounting, call the current instance.editor?.view.refreshFontMetrics() after readiness. Never refresh a discarded Core.

Cached assets, browser registration and exportable font bytes are different resources. fontLibrary.getInstallations() exposes completed installations. Local-only records contain no embeddable bytes, so browser availability does not guarantee embedded exports. Confirm resources and applicable rights for the selected export service.

Test first load, cache hits, offline behavior, failed downloads and mixed scripts. After readiness, inspect wrapping, page count and selection geometry, rather than only the font dropdown. See configuration types in the instance reference.