@docx-editor.dev/fonts/google
Functions (1)
googleFontsfunctionSource ↗
A [FontResolver](FontResolver) that serves the document's declared families from the pinned Google catalog — plus the package's own bundled faces for families the catalog has no metric-compatible answer for — loading only what that document turned out to need.
ts
<DocxEditor.Root fonts={googleFonts()} />
Same call shape as packagedFonts() from @docx-editor.dev/fonts, so the two compose by sitting next to each other: useFonts(packagedFonts(), googleFonts()) serves the bundled faces first and reaches the catalog only for what they do not cover.
Compose it with your own bytes by wrapping it — the resolver is an ordinary async function of the families, so a wrapper can merge fragments before returning.
declare function googleFonts(options?: GoogleFontsOptions): GoogleFontsResolver;Interfaces (4)
GoogleFontFaceinterfaceSource ↗
One fetchable face in the pinned catalog.
The catalog is a CLOSED set: a document-declared family is only ever a lookup key against it, never interpolated into a URL, so a crafted w:rFonts cannot redirect a fetch. Bytes are trusted by hash, not by origin.
interface GoogleFontFace| Member | Type | Summary |
|---|---|---|
| byteLength | number | Expected size; a response of any other length is rejected before use. |
| family | string | The family name a document would name, e.g. "PT Sans". |
| hash | string | `sha256:` digest the engine's admission path re-derives, catching a swapped CDN asset. |
| style | 'normal' | 'italic' | |
| url | string | Immutable, commit-pinned jsDelivr URL. |
| weight | 400 | 700 | Only the two static weights; variable-only families are excluded by the generator. |
GoogleFontLoadFailureinterfaceSource ↗
One face that did not arrive. Non-fatal: the resolver returns whatever else succeeded, and the affected family falls back to the engine's fixed measurement.
A hashMismatch does NOT appear here — bytes are trusted by content at the engine's admission path, which rejects them after this resolver has handed them over.
interface GoogleFontLoadFailure| Member | Type | Summary |
|---|---|---|
| diagnostic | string | |
| family | string | The family of the face that failed to load — the SERVING name ("Carlito", "TeX Gyre Adventor"), not the name the document wrote. A document naming Calibri sees "Carlito" here, because that is the file that did not arrive. |
| url | string | The pinned catalog URL, or the asset filename for a face served from the bundle. |
GoogleFontsFragmentinterfaceSource ↗
What one resolver call produced, for callers that want it without the editor.
interface GoogleFontsFragment| Member | Type | Summary |
|---|---|---|
| failures | readonly GoogleFontLoadFailure[] | |
| sources | readonly DefaultFontSource[] | |
| substitutions | readonly DefaultFontSubstitution[] | |
| supportedFamilies? | readonly string[] | Families this provider can serve after applying allow and substitute options. |
GoogleFontsOptionsinterfaceSource ↗
How googleFonts() behaves once a document hands it a family list. Every field is optional; googleFonts() with no options fetches any catalogued family a document names, over the global fetch, warning to the console on failure.
interface GoogleFontsOptions| Member | Type | Summary |
|---|---|---|
| allow? | readonly string[] | Narrow what may ever load, by the name of the face that would SERVE the request ("Carlito", "TeX Gyre Adventor"). Omitted, any family this module can answer is fair game; set it to run against a closed short list. |
| fetcher? | typeof fetch | Injectable for tests and CSP-constrained hosts; defaults to global `fetch`. |
| onFailure? | (failure: GoogleFontLoadFailure) => void | Per-face failures. Defaults to a console warning; pass a handler to route them. |
| substitute? | Readonly<Record<string, string>> | Extra document-family - catalog-family mappings, merged OVER [GOOGLE_METRIC_SUBSTITUTES](GOOGLE_METRIC_SUBSTITUTES). Only metric-compatible pairs keep pagination Word-accurate; anything else trades line breaks for closer-looking glyphs. |
Type aliases (1)
GoogleFontsResolvertypeSource ↗
What [googleFonts](googleFonts) returns: a marked resolver over the pinned catalog.
type GoogleFontsResolver = ((request: FontOriginRequest) => Promise<GoogleFontsFragment>) & FontResolverMark;Variables (4)
GOOGLE_FONT_CATALOGconstSource ↗
Every face googleFonts() may fetch, sorted by family then weight then style. Closed and pinned: nothing outside this list is reachable, which is what makes resolving a document-declared family name safe.
GOOGLE_FONT_CATALOG: readonly GoogleFontFace[]GOOGLE_FONT_FAMILIESconstSource ↗
Every family the catalog can serve, sorted — the set a font picker may offer.
GOOGLE_FONT_FAMILIES: readonly string[]GOOGLE_FONTS_REVISIONconstSource ↗
The main google/fonts catalog revision. Some static aliases use older immutable revisions because their current upstream families are variable-only.
GOOGLE_FONTS_REVISION = "ea14f3c4c462af1d847b1abe96fcb3c3a8a66f97"GOOGLE_METRIC_SUBSTITUTESconstSource ↗
Word families with a METRIC-COMPATIBLE catalogued stand-in: identical advance widths, so a document laid out on the substitute paginates like Word.
Arial and Helvetica are absent on purpose. Their match is Arimo, which google/fonts now ships variable-only, and the shaper refuses variation axes — a variable file would render bold at regular weight. defaultFonts() still covers them from the bundle.
GOOGLE_METRIC_SUBSTITUTES: Readonly<Record<string, string>>