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

# getPairingsByCategory

> Retrieve font pairings filtered by heading font category

## Function Signature

```typescript theme={null}
function getPairingsByCategory(category: FontCategory): PairingData[]
```

## Description

Filters and returns all font pairings where the heading font matches the specified category. This is useful when you want to enforce a specific typographic style for headings, such as all serif headings for a traditional look or sans-serif for modern designs.

The function filters based on the `headingCategory` property, not the body font category.

## Parameters

<ParamField path="category" type="FontCategory" required>
  The font category to filter by. Must be one of:

  * `"serif"` - Traditional fonts with decorative strokes (e.g., Libre Baskerville, Merriweather)
  * `"sans-serif"` - Modern fonts without decorative strokes (e.g., Outfit, Schibsted Grotesk)
  * `"monospace"` - Fixed-width fonts for code and technical content (e.g., IBM Plex Mono, Fira Code)

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

## Return Value

<ResponseField name="return" type="PairingData[]">
  An array of font pairings where the heading font belongs to the specified category. Returns an empty array if no pairings match.

  Each `PairingData` object contains:

  <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 (matches the search parameter)
    </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 (may differ from heading category)
    </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
    </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 configuration
    </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 { getPairingsByCategory } from '@/lib/pairings';

  const sansSerifPairings = getPairingsByCategory('sans-serif');

  console.log(`Found ${sansSerifPairings.length} sans-serif pairings`);
  sansSerifPairings.forEach(p => {
    console.log(`${p.name}: ${p.heading} (${p.headingCategory})`);
  });
  ```

  ```typescript Category Filter Component theme={null}
  import { getPairingsByCategory } from '@/lib/pairings';
  import { useState } from 'react';
  import type { FontCategory } from '@/lib/pairings';

  function CategoryFilter() {
    const [category, setCategory] = useState<FontCategory>('sans-serif');
    const pairings = getPairingsByCategory(category);
    
    return (
      <div>
        <div className="filters">
          <button onClick={() => setCategory('serif')}>
            Serif ({getPairingsByCategory('serif').length})
          </button>
          <button onClick={() => setCategory('sans-serif')}>
            Sans-serif ({getPairingsByCategory('sans-serif').length})
          </button>
          <button onClick={() => setCategory('monospace')}>
            Monospace ({getPairingsByCategory('monospace').length})
          </button>
        </div>
        
        <div className="results">
          {pairings.map(pairing => (
            <div key={pairing.name}>
              <h3>{pairing.heading}</h3>
              <p>+ {pairing.body}</p>
            </div>
          ))}
        </div>
      </div>
    );
  }
  ```

  ```typescript Find Contrasting Pairings theme={null}
  import { getPairingsByCategory } from '@/lib/pairings';
  import type { PairingData } from '@/lib/pairings';

  // Find pairings where heading and body have different categories
  function getContrastingPairings(): PairingData[] {
    const allCategories: FontCategory[] = ['serif', 'sans-serif', 'monospace'];
    const contrasting: PairingData[] = [];
    
    allCategories.forEach(category => {
      const pairings = getPairingsByCategory(category);
      const filtered = pairings.filter(
        p => p.bodyCategory !== p.headingCategory
      );
      contrasting.push(...filtered);
    });
    
    return contrasting;
  }

  const contrasting = getContrastingPairings();
  console.log(`${contrasting.length} pairings with contrasting categories`);
  ```

  ```typescript Category Statistics theme={null}
  import { getPairingsByCategory } from '@/lib/pairings';
  import type { FontCategory } from '@/lib/pairings';

  function getCategoryStats() {
    const categories: FontCategory[] = ['serif', 'sans-serif', 'monospace'];
    
    return categories.map(category => ({
      category,
      count: getPairingsByCategory(category).length,
      pairings: getPairingsByCategory(category)
        .map(p => p.name)
        .join(', ')
    }));
  }

  const stats = getCategoryStats();
  stats.forEach(({ category, count, pairings }) => {
    console.log(`${category}: ${count}`);
    console.log(`  ${pairings}`);
  });
  ```

  ```typescript Type-Safe Category Selection theme={null}
  import { getPairingsByCategory } from '@/lib/pairings';
  import type { FontCategory, PairingData } from '@/lib/pairings';

  interface DesignPreferences {
    headingStyle: FontCategory;
    modernLook: boolean;
  }

  function selectPairingByPreferences(
    prefs: DesignPreferences
  ): PairingData | null {
    const candidates = getPairingsByCategory(prefs.headingStyle);
    
    if (prefs.modernLook) {
      // Prefer sans-serif body fonts for modern look
      const modern = candidates.filter(p => p.bodyCategory === 'sans-serif');
      return modern[0] || candidates[0] || null;
    }
    
    return candidates[0] || null;
  }

  const pairing = selectPairingByPreferences({
    headingStyle: 'sans-serif',
    modernLook: true
  });

  if (pairing) {
    console.log(`Selected: ${pairing.name}`);
  }
  ```

  ```typescript Get All Categories with Counts theme={null}
  import { getPairingsByCategory } from '@/lib/pairings';
  import type { FontCategory } from '@/lib/pairings';

  function getCategoryCounts(): Record<FontCategory, number> {
    return {
      'serif': getPairingsByCategory('serif').length,
      'sans-serif': getPairingsByCategory('sans-serif').length,
      'monospace': getPairingsByCategory('monospace').length
    };
  }

  const counts = getCategoryCounts();
  console.log('Pairings by category:', counts);
  // Output: { serif: 5, sans-serif: 12, monospace: 1 }
  ```
</CodeGroup>

## Example Response

```json theme={null}
[
  {
    "name": "agency",
    "heading": "Schibsted Grotesk",
    "headingCategory": "sans-serif",
    "body": "Karla",
    "bodyCategory": "sans-serif",
    "mono": "Fira Code",
    "mood": ["minimal", "nordic"],
    "useCase": ["agency", "design", "portfolio"],
    "description": "Nordic minimalism meets grotesque warmth. Schibsted Grotesk's Scandinavian clarity in headlines paired with Karla's quirky grotesque personality for body text that feels human.",
    "scale": {
      "h1": {
        "size": "2.25rem",
        "weight": 700,
        "lineHeight": "1.15",
        "letterSpacing": "-0.03em"
      },
      "body": {
        "size": "1rem",
        "lineHeight": "1.6",
        "weight": 400
      }
    },
    "googleFontsUrl": "https://fonts.googleapis.com/css2?family=Schibsted+Grotesk:wght@400;500;600;700&family=Karla:wght@400;500;600&family=Fira+Code:wght@400;500&display=swap"
  },
  {
    "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"
      },
      "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

<Note>
  **Heading Category Only**: This function filters by `headingCategory`, not `bodyCategory`. The body font may be in a different category, which often creates interesting typographic contrast.
</Note>

<Warning>
  **Type Safety**: Use the `FontCategory` type from `@/lib/pairings` to ensure type safety. Invalid category strings will still execute but return an empty array.
</Warning>

<Tip>
  For modern web designs, `sans-serif` heading categories are most popular. For traditional or editorial designs, consider `serif` categories.
</Tip>

<Note>
  **Performance**: This function filters the entire pairings array on each call. Consider caching results if calling repeatedly with the same category.
</Note>

## Common Patterns

### Serif Headings

Serif heading fonts create a traditional, authoritative, or editorial feel. Common for:

* News and magazine sites
* Academic publications
* Literary content
* Traditional brands

### Sans-serif Headings

Sans-serif heading fonts create a modern, clean, minimal feel. Common for:

* Tech startups
* SaaS products
* Modern agencies
* Portfolio sites

### Monospace Headings

Monospace heading fonts create a technical, code-focused feel. Common for:

* Developer tools
* Technical documentation
* Code-heavy sites
* Retro/terminal aesthetics

## Related Functions

* [`getAllPairings`](/api/functions/get-all-pairings) - Get all available pairings
* [`getPairing`](/api/functions/get-pairing) - Get a specific pairing by name
* [`getPairingsByMood`](/api/functions/get-pairings-by-mood) - Filter by mood tag