getPairingsByCategory

Function Signature

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

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.

Return Value

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:

Show PairingData properties

string

required

Unique identifier for the pairing

string

required

Font family name for headings

FontCategory

required

Category of the heading font (matches the search parameter)

string

required

Font family name for body text

FontCategory

required

Category of the body font (may differ from heading category)

string

required

Font family name for monospace/code text

string[]

required

Array of mood tags

string[]

required

Array of recommended use cases

string

required

Human-readable description of the pairing

TypographyScale

required

Complete typography scale configuration

string

required

Ready-to-use Google Fonts URL

Usage Examples

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})`);
});

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>
  );
}

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`);

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}`);
});

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}`);
}

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 }

Example Response

[
  {
    "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

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.

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

For modern web designs, sans-serif heading categories are most popular. For traditional or editorial designs, consider serif categories.

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

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

getAllPairings - Get all available pairings
getPairing - Get a specific pairing by name
getPairingsByMood - Filter by mood tag

Registry API

JavaScript API

getPairingsByCategory

Function Signature

Description

Parameters

Return Value

Usage Examples

Example Response

Notes

Common Patterns

Serif Headings

Sans-serif Headings

Monospace Headings

​Function Signature

​Description

​Parameters

​Return Value

​Usage Examples

​Example Response

​Notes

​Common Patterns

​Serif Headings

​Sans-serif Headings

​Monospace Headings

​Related Functions

Function Signature

Description

Parameters

Return Value

Usage Examples

Example Response

Notes

Common Patterns

Serif Headings

Sans-serif Headings

Monospace Headings

Related Functions