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

# getPairing

> Retrieve a specific font pairing by its unique name

## Function Signature

```typescript theme={null}
function getPairing(name: string): PairingData | undefined
```

## Description

Retrieves a single font pairing by its unique identifier. This function searches through the Fonttrio registry and returns the matching pairing configuration, or `undefined` if no pairing with the given name exists.

## Parameters

<ParamField path="name" type="string" required>
  The unique identifier of the pairing to retrieve. Examples include:

  * `"agency"` - Nordic minimalism with Schibsted Grotesk
  * `"architect"` - Structured design with Outfit
  * `"minimal"` - Clean, modern aesthetics

  Name matching is case-sensitive and must match exactly.
</ParamField>

## Return Value

<ResponseField name="return" type="PairingData | undefined">
  Returns the matching `PairingData` object if found, or `undefined` if no pairing exists with the given name.

  <Expandable title="PairingData properties">
    <ResponseField name="name" type="string" required>
      Unique identifier for the pairing
    </ResponseField>

    <ResponseField name="heading" type="string" required>
      Font family name for headings
    </ResponseField>

    <ResponseField name="headingCategory" type="FontCategory" required>
      Category of the heading font: `"serif"`, `"sans-serif"`, or `"monospace"`
    </ResponseField>

    <ResponseField name="body" type="string" required>
      Font family name for body text
    </ResponseField>

    <ResponseField name="bodyCategory" type="FontCategory" required>
      Category of the body font: `"serif"`, `"sans-serif"`, or `"monospace"`
    </ResponseField>

    <ResponseField name="mono" type="string" required>
      Font family name for monospace/code text
    </ResponseField>

    <ResponseField name="mood" type="string[]" required>
      Array of mood tags describing the aesthetic
    </ResponseField>

    <ResponseField name="useCase" type="string[]" required>
      Array of recommended use cases
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Human-readable description of the pairing
    </ResponseField>

    <ResponseField name="scale" type="TypographyScale" required>
      Complete typography scale with h1-h6 and body configurations
    </ResponseField>

    <ResponseField name="googleFontsUrl" type="string" required>
      Ready-to-use Google Fonts URL
    </ResponseField>
  </Expandable>
</ResponseField>

## Usage Examples

<CodeGroup>
  ```typescript Basic Usage theme={null}
  import { getPairing } from '@/lib/pairings';

  const agencyPairing = getPairing('agency');

  if (agencyPairing) {
    console.log(`Heading: ${agencyPairing.heading}`);
    console.log(`Body: ${agencyPairing.body}`);
  } else {
    console.log('Pairing not found');
  }
  ```

  ```typescript With Error Handling theme={null}
  import { getPairing } from '@/lib/pairings';

  function loadPairing(pairingName: string) {
    const pairing = getPairing(pairingName);
    
    if (!pairing) {
      throw new Error(`Pairing "${pairingName}" not found`);
    }
    
    return pairing;
  }

  try {
    const pairing = loadPairing('agency');
    console.log('Loaded:', pairing.name);
  } catch (error) {
    console.error(error.message);
  }
  ```

  ```typescript Apply Typography Scale theme={null}
  import { getPairing } from '@/lib/pairings';

  function applyPairingStyles(pairingName: string) {
    const pairing = getPairing(pairingName);
    
    if (!pairing) return;
    
    // Apply to CSS custom properties
    document.documentElement.style.setProperty(
      '--font-heading',
      pairing.heading
    );
    document.documentElement.style.setProperty(
      '--font-body',
      pairing.body
    );
    document.documentElement.style.setProperty(
      '--h1-size',
      pairing.scale.h1.size
    );
    document.documentElement.style.setProperty(
      '--h1-weight',
      pairing.scale.h1.weight.toString()
    );
  }

  applyPairingStyles('architect');
  ```

  ```typescript Load Google Fonts theme={null}
  import { getPairing } from '@/lib/pairings';

  function loadPairingFonts(pairingName: string): boolean {
    const pairing = getPairing(pairingName);
    
    if (!pairing) return false;
    
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = pairing.googleFontsUrl;
    document.head.appendChild(link);
    
    return true;
  }

  loadPairingFonts('agency');
  ```

  ```typescript React Component theme={null}
  import { getPairing } from '@/lib/pairings';
  import { useEffect, useState } from 'react';

  function PairingPreview({ name }: { name: string }) {
    const [pairing, setPairing] = useState(getPairing(name));
    
    useEffect(() => {
      setPairing(getPairing(name));
    }, [name]);
    
    if (!pairing) {
      return <div>Pairing not found</div>;
    }
    
    return (
      <div>
        <h1 style={{ fontFamily: pairing.heading }}>
          {pairing.heading}
        </h1>
        <p style={{ fontFamily: pairing.body }}>
          {pairing.description}
        </p>
        <code style={{ fontFamily: pairing.mono }}>
          const example = true;
        </code>
      </div>
    );
  }
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "name": "architect",
  "heading": "Outfit",
  "headingCategory": "sans-serif",
  "body": "Libre Baskerville",
  "bodyCategory": "serif",
  "mono": "IBM Plex Mono",
  "mood": ["structured", "professional"],
  "useCase": ["portfolio", "agency", "architecture"],
  "description": "Structured meets refined. Outfit's geometric precision in headings contrasts beautifully with Libre Baskerville's warm readability, like blueprints meeting handwritten notes.",
  "scale": {
    "h1": {
      "size": "2.5rem",
      "weight": 700,
      "lineHeight": "1.1",
      "letterSpacing": "-0.03em"
    },
    "h2": {
      "size": "2rem",
      "weight": 600,
      "lineHeight": "1.15",
      "letterSpacing": "-0.025em"
    },
    "body": {
      "size": "1rem",
      "lineHeight": "1.6",
      "weight": 400
    }
  },
  "googleFontsUrl": "https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Libre+Baskerville:wght@400;700&family=IBM+Plex+Mono:wght@400;500&display=swap"
}
```

## Notes

<Warning>
  **Case Sensitivity**: Pairing names are case-sensitive. `"Agency"` will not match `"agency"`. Always use lowercase names as defined in the registry.
</Warning>

<Note>
  **Performance**: This function uses `Array.find()` which has O(n) complexity. For repeated lookups, consider caching the result or using a Map-based lookup if you need frequent access.
</Note>

<Tip>
  Always check for `undefined` before using the returned value. TypeScript will help enforce this check at compile time.
</Tip>

## Related Functions

* [`getAllPairings`](/api/functions/get-all-pairings) - Get all available pairings
* [`getPairingsByMood`](/api/functions/get-pairings-by-mood) - Filter pairings by mood
* [`getPairingsByCategory`](/api/functions/get-pairings-by-category) - Filter pairings by font category