Skip to main content

Customization

Learn how to customize Fluid Typography to match your design system.

Overview​

Fluid Typography works out-of-the-box with sensible defaults, but you can customize:

  • Custom Typography Scales - Add your own size scales
  • Viewport Range - Change min/max viewport widths
  • Typography Properties - Control line height, font weight, letter spacing, and text transform

Add Custom Scales​

Extend the default scales with your own custom typography classes.

Basic Custom Scale​

tailwind.config.ts
import fluidTypography from 'fluid-typography'

export default {
  plugins: [
    fluidTypography({
      customScales: {
        'hero': {
          size: [50, 80],  // [minPx, maxPx]
        }
      }
    })
  ]
}

Now use text-hero in your components:

<h1 className="text-hero">Custom Hero Text</h1>

Full Custom Scale Configuration​

Control all typography properties:

tailwind.config.ts
import fluidTypography from 'fluid-typography'

export default {
  plugins: [
    fluidTypography({
      customScales: {
        'hero': {
          size: [50, 80],              // Required: [minPx, maxPx]
          lineHeight: 1.1,              // Optional, defaults to 1.5
          fontWeight: '900',            // Optional, defaults to '400'
          letterSpacing: '-0.02em',     // Optional
          textTransform: 'uppercase'    // Optional: 'uppercase' | 'lowercase' | 'capitalize'
        },
        'mega': {
          size: [60, 120],
          lineHeight: 1.0,
          fontWeight: '800'
        }
      }
    })
  ]
}

Available Properties​

PropertyTypeDefaultDescription
size[number, number]RequiredMin and max font size in pixels
lineHeightnumber1.5Line height (unitless)
fontWeightstring'400'Font weight (e.g., '400', '700', '900')
letterSpacingstringundefinedLetter spacing with unit (e.g., '-0.02em', '0.1em')
textTransform'uppercase' | 'lowercase' | 'capitalize'undefinedText transform property

Customize Viewport Range​

Change the viewport width range for fluid scaling. Default is 375px → 1440px.

tailwind.config.ts
import fluidTypography from 'fluid-typography'

export default {
  plugins: [
    fluidTypography({
      minViewportWidth: 320,   // Scale from 320px
      maxViewportWidth: 1920   // Scale to 1920px
    })
  ]
}

Common Viewport Configurations​

Mobile First (Small to Large)​

{
  minViewportWidth: 320,
  maxViewportWidth: 1920
}

Tablet to Desktop​

{
  minViewportWidth: 768,
  maxViewportWidth: 1440
}

Narrow Range​

{
  minViewportWidth: 375,
  maxViewportWidth: 768
}

Combine Both​

Use custom scales and custom viewport ranges together:

tailwind.config.ts
import fluidTypography from 'fluid-typography'

export default {
  plugins: [
    fluidTypography({
      customScales: {
        'hero': {
          size: [50, 80],
          lineHeight: 1.1,
          fontWeight: '900',
          letterSpacing: '-0.02em'
        },
        'mega': {
          size: [60, 120],
          fontWeight: '800'
        }
      },
      minViewportWidth: 320,
      maxViewportWidth: 1920
    })
  ]
}

Tailwind v4 Configuration​

For Tailwind v4, you need a config file for customization:

tailwind.config.js
import fluidTypography from 'fluid-typography';

export default {
  plugins: [
    fluidTypography({
      customScales: {
        'hero': {
          size: [50, 80],
          fontWeight: '900'
        }
      },
      minViewportWidth: 320,
      maxViewportWidth: 1920
    })
  ]
};

Then reference it in your CSS:

app.css
@import "tailwindcss";
@config "./tailwind.config.js";

Default Scales Preserved​

Custom scales are added to the defaults, not replaced. You'll have access to:

  • All default classes (text-h1, text-body, etc.)
  • Your custom classes (text-hero, text-mega, etc.)
{/* Default scales still work */}
<h1 className="text-h1">Default Heading</h1>

{/* Custom scales available too */}
<h1 className="text-hero">Custom Hero</h1>

Using with Conditional Classes​

If you're using conditional rendering with custom scales, add them to the safelist:

tailwind.config.ts
import fluidTypography, { getTypographySafelist } from 'fluid-typography'

const options = {
  customScales: {
    'hero': { size: [50, 80] },
    'mega': { size: [60, 120] }
  }
}

export default {
  plugins: [fluidTypography(options)],
  safelist: getTypographySafelist(options)  // Pass same options
}

TypeScript Support​

All options are fully typed:

tailwind.config.ts
import type { Config } from 'tailwindcss'
import fluidTypography from 'fluid-typography'
import type { PluginOptions, ScaleConfig } from 'fluid-typography'

const typographyConfig: PluginOptions = {
  customScales: {
    'hero': {
      size: [50, 80],
      lineHeight: 1.1,
      fontWeight: '900'
    }
  },
  minViewportWidth: 320,
  maxViewportWidth: 1920
}

export default {
  plugins: [fluidTypography(typographyConfig)]
} satisfies Config

Real-World Examples​

Marketing Site​

fluidTypography({
  customScales: {
    'hero': { size: [48, 96], fontWeight: '900' },
    'subhero': { size: [32, 56], fontWeight: '700' }
  },
  minViewportWidth: 375,
  maxViewportWidth: 1920
})

Blog​

fluidTypography({
  customScales: {
    'article-title': { size: [32, 48], lineHeight: 1.2 },
    'article-lead': { size: [18, 22], lineHeight: 1.6 }
  },
  minViewportWidth: 320,
  maxViewportWidth: 800
})

Dashboard​

fluidTypography({
  customScales: {
    'metric': { size: [40, 60], fontWeight: '700' },
    'label': { size: [11, 13], fontWeight: '600', textTransform: 'uppercase' }
  },
  minViewportWidth: 1024,
  maxViewportWidth: 1920
})

Next Steps​