Skip to main content

​
getPairingGoogleFontsUrl

Returns the Google Fonts URL for a specific font pairing by name.

​
Function Signature

lib/pairings.ts
export function getPairingGoogleFontsUrl(name: string): string | null

​
Parameters

​
name
string
required
The name of the pairing (e.g., “editorial”, “minimal”, “brutalist”)

​
Returns

​
url
string | null
The Google Fonts URL for the pairing, or null if the pairing is not found or has no URL configured

​
Description

The getPairingGoogleFontsUrl() function retrieves the Google Fonts URL for a specific pairing. This URL includes all three fonts (heading, body, mono) with their required weights, optimized for loading in a single request.

​
Usage Examples

​
Basic Usage

import { getPairingGoogleFontsUrl } from '@/lib/pairings'

const url = getPairingGoogleFontsUrl('editorial')
console.log(url)
// Output: "https://fonts.googleapis.com/css2?family=Playfair+Display:wght@600;700&family=Source+Serif+4:wght@400;600&family=JetBrains+Mono:wght@400;500&display=swap"

​
Load Fonts Dynamically

import { getPairingGoogleFontsUrl } from '@/lib/pairings'

function loadPairingFonts(pairingName: string) {
  const url = getPairingGoogleFontsUrl(pairingName)
  
  if (!url) {
    console.error(`No Google Fonts URL found for pairing: ${pairingName}`)
    return
  }
  
  // Create and inject stylesheet
  const link = document.createElement('link')
  link.rel = 'stylesheet'
  link.href = url
  document.head.appendChild(link)
}

// Usage
loadPairingFonts('minimal')

​
Preload Pairing Fonts

import { getPairingGoogleFontsUrl } from '@/lib/pairings'

export function PairingFontLoader({ pairing }: { pairing: string }) {
  const url = getPairingGoogleFontsUrl(pairing)
  
  if (!url) return null
  
  return (
    <link
      rel="preload"
      as="style"
      href={url}
      onLoad="this.rel='stylesheet'"
    />
  )
}

// Usage in layout
<PairingFontLoader pairing="editorial" />

​
Next.js Font Loading

'use client'

import { useEffect, useState } from 'react'
import { getPairingGoogleFontsUrl } from '@/lib/pairings'

export function DynamicFontLoader({ pairing }: { pairing: string }) {
  const [loaded, setLoaded] = useState(false)
  
  useEffect(() => {
    const url = getPairingGoogleFontsUrl(pairing)
    if (!url) return
    
    const link = document.createElement('link')
    link.rel = 'stylesheet'
    link.href = url
    link.onload = () => setLoaded(true)
    document.head.appendChild(link)
    
    return () => {
      document.head.removeChild(link)
    }
  }, [pairing])
  
  return loaded ? (
    <div style={{ fontFamily: 'var(--font-heading)' }}>
      Fonts loaded!
    </div>
  ) : (
    <div>Loading fonts...</div>
  )
}

​
Error Handling

import { getPairingGoogleFontsUrl } from '@/lib/pairings'

function getFontsUrlSafely(pairingName: string): string {
  const url = getPairingGoogleFontsUrl(pairingName)
  
  if (!url) {
    throw new Error(`Pairing "${pairingName}" not found or has no Google Fonts URL`)
  }
  
  return url
}

// Usage with try/catch
try {
  const url = getFontsUrlSafely('nonexistent')
  console.log(url)
} catch (error) {
  console.error(error.message)
  // Fallback to default fonts
}

​
Generate Font Preconnect Tags

import { getPairingGoogleFontsUrl } from '@/lib/pairings'

export function FontPreconnect({ pairing }: { pairing: string }) {
  const url = getPairingGoogleFontsUrl(pairing)
  
  if (!url) return null
  
  return (
    <>
      <link rel="preconnect" href="https://fonts.googleapis.com" />
      <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />
      <link rel="stylesheet" href={url} />
    </>
  )
}

​
URL Format

The returned URL follows the Google Fonts API v2 format: 
https://fonts.googleapis.com/css2?family=Font1:wght@weights&family=Font2:wght@weights&display=swap
Example for the “Editorial” pairing: 
https://fonts.googleapis.com/css2?family=Playfair+Display:wght@600;700&family=Source+Serif+4:wght@400;600&family=JetBrains+Mono:wght@400;500&display=swap
This URL includes:
  • Heading font: Playfair Display (weights: 600, 700)
  • Body font: Source Serif 4 (weights: 400, 600)
  • Mono font: JetBrains Mono (weights: 400, 500)
  • Display strategy: swap (shows fallback text immediately)

​
Return Value

​
url
string | null
  • Returns the full Google Fonts URL as a string if the pairing exists
  • Returns null if:
    • The pairing name is not found in the registry
    • The pairing exists but has no googleFontsUrl field (rare)
Always check for null before using the returned URL to avoid runtime errors.

getPairing

Get full pairing data including fonts and scale

getAllGoogleFontsUrls

Get all Google Fonts URLs across pairings

​
Notes

  • The function internally calls getPairing() to fetch the pairing data
  • Pairing names are case-sensitive (use lowercase names like “editorial”, not “Editorial”)
  • All current pairings include a Google Fonts URL, but the function returns null for safety
  • URLs include display=swap for optimal loading performance
  • Performance: O(n) where n is the number of pairings (linear search)

​
Common Pairings

  • editorial - Playfair Display + Source Serif 4 + JetBrains Mono
  • literary - EB Garamond + Crimson Text + Inconsolata
  • newspaper - Playfair Display + DM Sans + JetBrains Mono
  • minimal - Inter + Inter + JetBrains Mono
  • modern-clean - Space Grotesk + Space Grotesk + Space Mono
  • swiss - Work Sans + Work Sans + Source Code Pro
  • brutalist - Space Grotesk + Space Grotesk + Space Mono
  • impact - Bebas Neue + Barlow + Fira Code
  • poster - Alfa Slab One + Assistant + Roboto Mono

​
Source Reference

Implementation: lib/pairings.ts:63-66

Build docs developers (and LLMs) love

Get started for freeTalk to us