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:

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

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

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

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

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:

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

What gets installed

The shadcn CLI will:

Download font configurations from the Fonttrio registry
Install three fonts (heading, body, mono) via next/font/google

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

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

Configure font loading in your root layout

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:

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

CSS variables not found

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

Verify the pairing was installed:

cat app/globals.css | grep "font-heading"

Ensure globals.css is imported in your root layout:
```
// app/layout.tsx
import './globals.css'
```
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:

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

shadcn CLI errors

Symptom: shadcn add command fails.Solutions:

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

Font weights look wrong

Symptom: Fonts appear too bold or too light.Solutions:

Check which font weights are loaded in the registry JSON
Google Fonts may not include all weights for every font

Customize weight in your CSS:

h1 {
  font-weight: 600; /* Adjust as needed */
}

Some fonts have optical size variants - check if that’s enabled

Performance issues

Symptom: Slow page loads or layout shift.Solutions:

Fonttrio uses next/font which includes automatic optimization
Fonts are loaded from Google Fonts CDN with optimal caching
Reduce number of font weights if performance is critical
Use font-display: swap (default in next/font)
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.

Get Started

Core Concepts

Guides

Collections

Installation

Installation

Requirements

Next.js 14+

shadcn/ui

Tailwind CSS

Prerequisites Setup

Installing a Font Pairing

Registry Structure

Using Fonts in Your App

Automatic HTML Element Styling

Using CSS Variables Directly

In Tailwind Config

Installing Multiple Pairings

Customizing Typography Scale

Troubleshooting

Best Practices

Font Loading

CSS Variables

Typography Scale

Customization

Next Steps

Quickstart

Browse Pairings

Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Collections

​Installation

​Requirements

Next.js 14+

shadcn/ui

Tailwind CSS

​Prerequisites Setup

​Installing a Font Pairing

​Registry Structure

​Using Fonts in Your App

​Automatic HTML Element Styling

​Using CSS Variables Directly

​In Tailwind Config

​Installing Multiple Pairings

​Customizing Typography Scale

​Troubleshooting

​Best Practices

Font Loading

CSS Variables

Typography Scale

Customization

​Next Steps

Quickstart

Browse Pairings

Examples

Build docs developers (and LLMs) love

Installation

Requirements

Prerequisites Setup

Installing a Font Pairing

Registry Structure

Using Fonts in Your App

Automatic HTML Element Styling

Using CSS Variables Directly

In Tailwind Config

Installing Multiple Pairings

Customizing Typography Scale

Troubleshooting

Best Practices

Next Steps