Installation

Detailed installation instructions for Fonttrio font pairings in Next.js projects.

Installation

This guide covers everything you need to know about installing and setting up Fonttrio in your project.

Requirements

Before installing Fonttrio, ensure your project meets these requirements:

Next.js 14+

App Router required for next/font support

shadcn/ui

CLI must be installed and configured

Tailwind CSS

Required for utility classes

Fonttrio uses the shadcn/ui registry system, which requires the shadcn CLI to be installed in your project.

Prerequisites Setup

If you’re starting a new project, follow these steps:

1. Create a Next.js project

   Create a new Next.js 14+ project with the App Router:

   npx create-next-app@latest my-app
   

   When prompted, select:

   • ✅ TypeScript
   • ✅ Tailwind CSS
   • ✅ App Router
2. Initialize shadcn/ui

   Install and configure shadcn/ui in your project:

   npx shadcn@latest init
   

   This will:

   • Install required dependencies
   • Create components.json configuration
   • Set up your components/ui directory
   • Configure your tailwind.config and globals.css
3. Verify setup

   Ensure your project has these files:

   • app/layout.tsx - App Router layout
   • app/globals.css - Global styles
   • components.json - shadcn configuration
   • tailwind.config.ts - Tailwind configuration

Installing a Font Pairing

1. Browse available pairings

   Visit fonttrio.xyz to browse all 49 curated pairings. Each pairing page includes:

   • Live preview with actual fonts
   • Typography scale visualization
   • Interactive type tester
   • Context previews (blog, landing, docs)
   • One-click copy install command
2. Copy the install command

   Each pairing has a unique registry URL. The install command follows this pattern:

   npx shadcn@latest add https://www.fonttrio.xyz/r/{pairing-name}.json
   

   For example, to install the Editorial pairing:

   npm

   npx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
   

   pnpm dlx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
   

   yarn dlx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
   

   bunx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
   
3. What gets installed

   The shadcn CLI will:

   1. Download font configurations from the Fonttrio registry
   2. Install three fonts (heading, body, mono) via next/font/google
   3. Add CSS variables to your app/globals.css:
      :root {
        --font-heading: var(--font-playfair-display);
        --font-body: var(--font-source-serif-4);
        --font-mono: var(--font-jetbrains-mono);
      }
      
   4. Apply typography scale with optimized sizing:
      h1 {
        font-family: var(--font-heading);
        font-size: 2.25rem;
        line-height: 1.2;
        letter-spacing: -0.025em;
        font-weight: 700;
      }
      
   5. Configure font loading in your root layout
4. Verify installation

   Check your app/globals.css file. You should see:

   • Font variable declarations in :root
   • Typography scale styles for h1-h6
   • Body and code font assignments

   Example output for the Editorial pairing:

   /* Font variables */
   :root {
     --font-heading: var(--font-playfair-display);
     --font-body: var(--font-source-serif-4);
     --font-mono: var(--font-jetbrains-mono);
   }
   
   /* Typography scale */
   h1 {
     font-family: var(--font-heading);
     font-size: 2.25rem;
     line-height: 1.2;
     letter-spacing: -0.025em;
     font-weight: 700;
   }
   
   h2 {
     font-family: var(--font-heading);
     font-size: 1.875rem;
     line-height: 1.25;
     letter-spacing: -0.02em;
     font-weight: 600;
   }
   
   /* ... more styles ... */
   
   body, p {
     font-family: var(--font-body);
     line-height: 1.65;
   }
   
   code, pre {
     font-family: var(--font-mono);
   }
   

Registry Structure

Each pairing is distributed as a JSON registry item:

{
  "name": "pairing-editorial",
  "type": "registry:style",
  "extends": "none",
  "title": "Editorial — Playfair Display + Source Serif 4 + JetBrains Mono",
  "description": "Classic editorial pairing. High-contrast serif headings with readable serif body text.",
  "categories": ["serif", "editorial", "elegant"],
  "registryDependencies": [
    "https://www.fonttrio.xyz/r/playfair-display.json",
    "https://www.fonttrio.xyz/r/source-serif-4.json",
    "https://www.fonttrio.xyz/r/jetbrains-mono.json"
  ],
  "cssVars": {
    "theme": {
      "--font-heading": "var(--font-playfair-display)",
      "--font-body": "var(--font-source-serif-4)",
      "--font-mono": "var(--font-jetbrains-mono)"
    }
  },
  "css": {
    "h1": {
      "font-family": "var(--font-heading)",
      "font-size": "2.25rem",
      "line-height": "1.2",
      "letter-spacing": "-0.025em",
      "font-weight": "700"
    }
    // ... more styles
  },
  "meta": {
    "mood": ["elegant", "traditional", "authoritative"],
    "useCase": ["blog", "editorial", "magazine", "documentation"]
  }
}

Using Fonts in Your App

After installation, fonts are available throughout your project:

Automatic HTML Element Styling

The typography scale automatically styles HTML elements:

export default function Page() {
  return (
    <div>
      <h1>This uses --font-heading</h1>
      <h2>This also uses --font-heading</h2>
      <p>This uses --font-body</p>
      <code>This uses --font-mono</code>
    </div>
  )
}

Using CSS Variables Directly

For custom components, use the CSS variables with Tailwind:

export default function CustomCard() {
  return (
    <div className="font-[family-name:var(--font-body)]">
      <h3 className="font-[family-name:var(--font-heading)] text-2xl">
        Card Title
      </h3>
      <p className="text-muted-foreground">
        Card description text
      </p>
    </div>
  )
}

In Tailwind Config

You can also extend your Tailwind config to create utility classes:

// tailwind.config.ts
export default {
  theme: {
    extend: {
      fontFamily: {
        heading: 'var(--font-heading)',
        body: 'var(--font-body)',
        mono: 'var(--font-mono)',
      },
    },
  },
}

Then use them as Tailwind classes:

<h1 className="font-heading">Heading</h1>
<p className="font-body">Body text</p>
<code className="font-mono">Code</code>

Installing Multiple Pairings

You can install multiple pairings in the same project:

npx shadcn@latest add https://www.fonttrio.xyz/r/editorial.json
npx shadcn@latest add https://www.fonttrio.xyz/r/minimal.json
npx shadcn@latest add https://www.fonttrio.xyz/r/corporate.json

All fonts will be loaded, and you can switch between pairings by updating the CSS variables:

/* Use Editorial */
:root {
  --font-heading: var(--font-playfair-display);
  --font-body: var(--font-source-serif-4);
  --font-mono: var(--font-jetbrains-mono);
}

/* Or use Minimal */
:root {
  --font-heading: var(--font-inter);
  --font-body: var(--font-inter);
  --font-mono: var(--font-jetbrains-mono);
}

Customizing Typography Scale

You can customize the typography scale by editing globals.css:

h1 {
  font-family: var(--font-heading);
  font-size: 3rem; /* Increased from 2.25rem */
  line-height: 1.1; /* Tightened from 1.2 */
  letter-spacing: -0.03em; /* More negative spacing */
  font-weight: 800; /* Bolder */
}

Troubleshooting

Fonts not loading

Symptom: Fonts don’t appear after installation.

Solutions:

1. Clear your browser cache and hard refresh (Cmd/Ctrl + Shift + R)
2. Restart your Next.js dev server
3. Check that CSS variables are present in globals.css
4. Verify next/font is working:
   npm list next
   
5. Check browser console for font loading errors

CSS variables not found

Symptom: Console shows “CSS variable not found” errors.

Solutions:

1. Verify the pairing was installed:
   cat app/globals.css | grep "font-heading"
   
2. Ensure globals.css is imported in your root layout:
   // app/layout.tsx
   import './globals.css'
   
3. Check CSS variable syntax - should use var(--font-heading) not --font-heading

Typography scale not applying

Symptom: HTML elements don’t have the expected styling.

Solutions:

1. Check CSS specificity - your custom styles may be overriding Fonttrio
2. Ensure no other CSS is resetting h1-h6 styles
3. Verify the typography scale CSS is present after the variables in globals.css
4. Try using !important temporarily to diagnose specificity issues

shadcn CLI errors

Symptom: shadcn add command fails.

Solutions:

1. Verify shadcn is initialized:
   cat components.json
   
2. Update to latest shadcn version:
   npm install -g shadcn@latest
   
3. Check internet connection - registry must be reachable
4. Try with full URL including .json extension

Font weights look wrong

Symptom: Fonts appear too bold or too light.

Solutions:

1. Check which font weights are loaded in the registry JSON
2. Google Fonts may not include all weights for every font
3. Customize weight in your CSS:
   h1 {
     font-weight: 600; /* Adjust as needed */
   }
   
4. Some fonts have optical size variants - check if that’s enabled

Performance issues

Symptom: Slow page loads or layout shift.

Solutions:

1. Fonttrio uses next/font which includes automatic optimization
2. Fonts are loaded from Google Fonts CDN with optimal caching
3. Reduce number of font weights if performance is critical
4. Use font-display: swap (default in next/font)
5. Consider font subsetting for non-Latin characters

Best Practices

Font Loading

• Let next/font handle optimization
• Don’t manually load Google Fonts
• Keep font weights minimal (2-3 max)
• Use variable fonts when available

CSS Variables

• Use the provided variables consistently
• Don’t hardcode font family names
• Extend in Tailwind config for convenience
• Document any customizations

Typography Scale

• Maintain consistent scale ratios
• Test at different viewport sizes
• Use relative units (rem) for accessibility
• Keep line heights readable (1.5-1.65 for body)

Customization

• Start with defaults, then customize
• Test changes across all components
• Document your scale in design system
• Consider dark mode contrast

Next Steps

Quickstart

Get started in under 2 minutes

Browse Pairings

Explore all 49 curated pairings

Examples

See real-world usage examples

License Note: All fonts distributed through Fonttrio are from Google Fonts and are open source. Check individual font licenses for commercial use terms.