Build Fluid Responsive Designs with fluid-tailwindcss Plugin

fluid-tailwindcss is a Tailwind CSS plugin that automates fluid typography and spacing using CSS clamp() functions.

It calculates values that scale smoothly between a minimum and maximum viewport width.

You can apply these fluid values directly in your HTML classes to replace complex media query breakpoints.

The Plugin is inspired by Maxwell Barvian’s fluid-tailwind plugin, but adds support for the latest TailwindCSS 4.

Features

How to Use It

1. Install the package through your preferred package manager:

npm install fluid-tailwindcss

For pnpm:

pnpm add fluid-tailwindcss

For Yarn:

yarn add fluid-tailwindcss

2. TailwindCSS v4 uses CSS-based configuration. Add the plugin to your main CSS file with the @plugin directive:

/* app.css */
@import "tailwindcss";
@plugin "fluid-tailwindcss";

You can configure the plugin directly in CSS:

@import "tailwindcss";
@plugin "fluid-tailwindcss" {
  minViewport: 320;
  maxViewport: 1920;
  checkAccessibility: true;
}

3. The plugin also supports the legacy TailwindCSS 3. Install with the legacy peer deps flag:

npm install fluid-tailwindcss --legacy-peer-deps

For pnpm:

pnpm add fluid-tailwindcss --ignore-peer-deps

Add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [
    require('fluid-tailwindcss')({
      minViewport: 375,
      maxViewport: 1440,
      useRem: true,
      rootFontSize: 16,
      checkAccessibility: true,
    })
  ]
}

4. The syntax follows a simple pattern: fl-{utility}-{min}/{max}. The prefix fl- identifies fluid utilities. The utility name matches standard Tailwind utilities. The min and max values reference the Tailwind scale.

<h1 class="fl-text-2xl/5xl fl-p-4/8">
  Fluid Typography and Spacing
</h1>

This generates CSS with clamp() functions:

.fl-text-2xl\/5xl {
  font-size: clamp(1.5rem, 1.0282rem + 2.0657vw, 3rem);
}
.fl-p-4\/8 {
  padding: clamp(1rem, 0.5282rem + 2.0657vw, 2rem);
}

5. Scale font sizes smoothly across viewports:

<!-- Heading that scales from text-xl to text-4xl -->
<h2 class="fl-text-xl/4xl">Responsive Heading</h2>
<!-- Body text that scales from text-sm to text-lg -->
<p class="fl-text-sm/lg">Paragraph content scales with viewport.</p>
<!-- Adjust line height fluidly -->
<p class="fl-text-base/xl fl-leading-6/8">
  Text with fluid line height
</p>

6. Create fluid padding and margins:

<!-- Card with fluid padding -->
<div class="fl-p-4/12 fl-m-2/8">
  Card content
</div>
<!-- Grid with fluid gap -->
<div class="grid grid-cols-3 fl-gap-2/6">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>
<!-- Directional spacing -->
<section class="fl-px-4/16 fl-py-8/20">
  Section with asymmetric fluid padding
</section>

7. Apply fluid dimensions to elements:

<!-- Fluid width and height -->
<div class="fl-w-64/96 fl-h-32/64">
  Responsive box
</div>
<!-- Fluid max-width for containers -->
<main class="fl-max-w-screen-sm/screen-xl mx-auto">
  Centered container that grows fluidly
</main>
<!-- Fluid minimum heights -->
<section class="fl-min-h-screen/screen">
  Full-height section
</section>

8. You can use custom values with matching units:

<!-- Custom rem values -->
<div class="fl-p-[1.5rem/3rem]">Custom padding range</div>
<!-- Custom pixel values -->
<div class="fl-w-[200px/800px]">Custom width range</div>
<!-- Custom em values for typography -->
<p class="fl-text-[0.875em/1.25em]">Custom font size range</p>

Both values must use the same unit. Mixed units like fl-p-[1rem/16px] will not work.

9. The plugin includes merge configuration for proper class conflict resolution. Import the customized version:

import { twMerge } from 'fluid-tailwindcss/tailwind-merge'
// Fluid utility wins when last
const classes1 = twMerge('p-4', 'fl-p-4/8')
// Result: 'fl-p-4/8'
// Regular utility wins when last
const classes2 = twMerge('fl-p-4/8', 'p-4')
// Result: 'p-4'
// Different utilities coexist
const classes3 = twMerge('fl-p-4/8', 'fl-m-2/6', 'text-lg')
// Result: 'fl-p-4/8 fl-m-2/6 text-lg'

Extend your existing tailwind-merge configuration:

import { extendTailwindMerge } from 'tailwind-merge'
import { withFluid } from 'fluid-tailwindcss/tailwind-merge'
const customMerge = extendTailwindMerge(withFluid, {
  // Your additional configuration
  extend: {
    classGroups: {
      // Custom class groups
    }
  }
})

Configuration Options

Supported Utilities

Spacing Utilities

• fl-p-{min}/{max}: Fluid padding (all sides)
• fl-px-{min}/{max}: Fluid horizontal padding
• fl-py-{min}/{max}: Fluid vertical padding
• fl-pt-{min}/{max}, fl-pr-{min}/{max}, fl-pb-{min}/{max}, fl-pl-{min}/{max}: Fluid individual padding sides
• fl-ps-{min}/{max}, fl-pe-{min}/{max}: Fluid inline padding (start/end)
• fl-m-{min}/{max}: Fluid margin (all sides)
• fl-mx-{min}/{max}: Fluid horizontal margin
• fl-my-{min}/{max}: Fluid vertical margin
• fl-mt-{min}/{max}, fl-mr-{min}/{max}, fl-mb-{min}/{max}, fl-ml-{min}/{max}: Fluid individual margin sides
• fl-ms-{min}/{max}, fl-me-{min}/{max}: Fluid inline margin (start/end)

Typography Utilities

• fl-text-{min}/{max}: Fluid font size
• fl-leading-{min}/{max}: Fluid line height
• fl-tracking-{min}/{max}: Fluid letter spacing

Sizing Utilities

• fl-w-{min}/{max}: Fluid width
• fl-h-{min}/{max}: Fluid height
• fl-size-{min}/{max}: Fluid width and height together
• fl-min-w-{min}/{max}: Fluid minimum width
• fl-max-w-{min}/{max}: Fluid maximum width
• fl-min-h-{min}/{max}: Fluid minimum height
• fl-max-h-{min}/{max}: Fluid maximum height

Layout Utilities

• fl-gap-{min}/{max}: Fluid gap (grid and flex)
• fl-gap-x-{min}/{max}: Fluid column gap
• fl-gap-y-{min}/{max}: Fluid row gap
• fl-inset-{min}/{max}: Fluid positioning offset (all sides)
• fl-top-{min}/{max}, fl-right-{min}/{max}, fl-bottom-{min}/{max}, fl-left-{min}/{max}: Fluid individual positioning
• fl-space-x-{min}/{max}: Fluid horizontal space between children
• fl-space-y-{min}/{max}: Fluid vertical space between children

Border Utilities

• fl-rounded-{min}/{max}: Fluid border radius (all corners)
• fl-rounded-t-{min}/{max}, fl-rounded-r-{min}/{max}, fl-rounded-b-{min}/{max}, fl-rounded-l-{min}/{max}: Fluid side border radius
• fl-rounded-tl-{min}/{max}, fl-rounded-tr-{min}/{max}, fl-rounded-br-{min}/{max}, fl-rounded-bl-{min}/{max}: Fluid corner border radius
• fl-border-{min}/{max}: Fluid border width

Transform Utilities

• fl-translate-x-{min}/{max}: Fluid horizontal translation
• fl-translate-y-{min}/{max}: Fluid vertical translation

Scroll Utilities

• fl-scroll-m-{min}/{max}, fl-scroll-mx-{min}/{max}, fl-scroll-my-{min}/{max}: Fluid scroll margin
• fl-scroll-p-{min}/{max}, fl-scroll-px-{min}/{max}, fl-scroll-py-{min}/{max}: Fluid scroll padding

FAQs

Q: Can I use fluid utilities with arbitrary values?
A: Yes. Write custom values inside square brackets like fl-p-[1rem/3rem]. Both values must use the same unit. Mixed units like fl-p-[1rem/16px] will cause errors.

Q: How do I disable accessibility warnings?
A: Set checkAccessibility: false in your plugin configuration. For TailwindCSS v4, add this to your CSS: @plugin "fluid-tailwindcss" { checkAccessibility: false; }. For v3, pass it in the JavaScript config object.

Q: Do fluid utilities work with tailwind-merge?
A: Yes. Import twMerge from fluid-tailwindcss/tailwind-merge instead of the standard package.

Q: What happens outside the viewport range?
A: Values clamp at the minimum and maximum thresholds. Below the minViewport, the minimum value applies. Above the maxViewport, the maximum value applies. No further scaling occurs outside this range.