> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kapishdima/fonttrio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript lib/pairings.ts theme={null}
export function getPairingGoogleFontsUrl(name: string): string | null
```

## Parameters

<ParamField path="name" type="string" required>
  The name of the pairing (e.g., "editorial", "minimal", "brutalist")
</ParamField>

## Returns

<ResponseField name="url" type="string | null">
  The Google Fonts URL for the pairing, or `null` if the pairing is not found or has no URL configured
</ResponseField>

## 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

```typescript theme={null}
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

```typescript theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
'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

```typescript theme={null}
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

```tsx theme={null}
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

<ResponseField name="url" type="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)
</ResponseField>

<Warning>
  Always check for `null` before using the returned URL to avoid runtime errors.
</Warning>

## Related Functions

<CardGroup cols={2}>
  <Card title="getPairing" icon="font" href="/api/functions/get-pairing">
    Get full pairing data including fonts and scale
  </Card>

  <Card title="getAllGoogleFontsUrls" icon="link" href="/api/functions/get-all-google-fonts-urls">
    Get all Google Fonts URLs across pairings
  </Card>
</CardGroup>

## 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

<AccordionGroup>
  <Accordion title="Editorial Pairings">
    * `editorial` - Playfair Display + Source Serif 4 + JetBrains Mono
    * `literary` - EB Garamond + Crimson Text + Inconsolata
    * `newspaper` - Playfair Display + DM Sans + JetBrains Mono
  </Accordion>

  <Accordion title="Clean Pairings">
    * `minimal` - Inter + Inter + JetBrains Mono
    * `modern-clean` - Space Grotesk + Space Grotesk + Space Mono
    * `swiss` - Work Sans + Work Sans + Source Code Pro
  </Accordion>

  <Accordion title="Bold Pairings">
    * `brutalist` - Space Grotesk + Space Grotesk + Space Mono
    * `impact` - Bebas Neue + Barlow + Fira Code
    * `poster` - Alfa Slab One + Assistant + Roboto Mono
  </Accordion>
</AccordionGroup>

## Source Reference

Implementation: `lib/pairings.ts:63-66`