getPairingGoogleFontsUrl

Get the Google Fonts URL for a specific font pairing

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.

Related Functions

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 Pairings

• editorial - Playfair Display + Source Serif 4 + JetBrains Mono
• literary - EB Garamond + Crimson Text + Inconsolata
• newspaper - Playfair Display + DM Sans + JetBrains Mono

Clean Pairings

• minimal - Inter + Inter + JetBrains Mono
• modern-clean - Space Grotesk + Space Grotesk + Space Mono
• swiss - Work Sans + Work Sans + Source Code Pro

Bold Pairings

• 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