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 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 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
Unique identifier for the pairing
Font family name for headings
Category of the heading font (matches the search parameter)
Font family name for body text
Category of the body font (may differ from heading category)
Font family name for monospace/code text
Array of recommended use cases
Human-readable description of the pairing
Complete typography scale configuration
Ready-to-use Google Fonts URL
Usage Examples Basic Usage
Category Filter Component
Find Contrasting Pairings
Category Statistics
Type-Safe Category Selection
Get All Categories with Counts
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 } )` ); });
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
