Features
- Works with every utility (including plugins)
- Full IntelliSense support
- First-class tailwind-merge support
- Ensures fluid type meets accessibility requirements
- Flexible enough to handle advanced use cases
Installation
Install the package
Install
fluid-tailwind
via npm.Add the plugin and extractor
The custom extractor lets you use the new
~
modifier in your Tailwind classes.Continue reading to the end of the limitations section
There may be additional installation steps depending on your Tailwind configuration.
Basic usage
Your browser isn't wide enough to see the full effect
Here’s a quick overview:
- The
~
modifier makes a utility fluid - Fluid utilities scale between their start/end values when the viewport is between the start and end breakpoints
- The start and end breakpoints default to the smallest and largest screen, but they can be customized or overridden per-utility
Limitations
Due to CSS restrictions, fluid utilities require the start/end values and breakpoints to be length literals (i.e. 1rem
) with the same unit.
Values with different units
Values with different units than breakpoints
Non-literal values like calc()
Non-lengths like colors
Tailwind’s default theme
Tailwind v3’s default breakpoints are in px
, while its default
spacing and
font sizes are in rem
.
This doesn’t bode well with the CSS restrictions mentioned above, so fluid-tailwind
provides rem
replacements
for the default breakpoints:
Similarly, the line heights used for Tailwind’s default font sizes 5xl
–9xl
are unitless, which can’t be fluidized.
fluid-tailwind
provides rem
replacements for those as well:
Configuration
Custom default breakpoints
The default start/end breakpoints can be set with a tuple of length literals [start, end]
.
Either can be omitted, in which case the plugin will use your smallest and largest
breakpoint, respectively.
Fluid type accessibility checks
By default, the plugin will not generate fluid type that would fail WCAG Success Criterion 1.4.4.
You can configure this with the checkSC144
option:
Advanced
Customize breakpoints per-utility
You can customize the start/end breakpoints for a fluid utility with
the included ~
variant. For example:
Your browser isn't wide enough to see the full effect
You can omit either start or end breakpoint to use your defaults:
Set start breakpoint to md
, end breakpoint to default
Set end breakpoint to lg
, start breakpoint to default
Arbitrary start breakpoint
If you want to set an arbitrary start breakpoint with the ~
variant, you have to use
~min-[]
(just as you’d have to use min-[]
to set an arbitrary breakpoint):
Trying to use ~[]:
to set an arbitrary start breakpoint
Using ~min-[]
to set an arbitrary start breakpoint
Negative values
To negate fluid utilities, the dash comes after the fluid ~
modifier:
Negating a fluid utility
Container queries
If you have the official container query plugin
installed, you can make fluid utilities scale between the nearest @container
widths rather than screen breakpoints by using the ~@
variant:
This may look confusing if you use named containers. Sorry about that; there’s only so many ways to pass data into Tailwind. In general, when you see the fluid ~
modifier, you know the /
denotes a start/end pair.
Just like the ~
variant, both start and end containers are optional and will use your defaults if unset.
Set end container to lg
, start container to default
Custom default containers
The default containers can be set in the same way as breakpoints. Either can be omitted, in which case the plugin will use your smallest and largest container, respectively.
Combining with media queries
To really get crazy, you can combine fluid utilities with container or media queries, as such:
Your browser isn't wide enough to see the full effect
Here’s how this works:
- We scale our font-size between
base
and4xl
between our smallest andmd
breakpoints - We scale in the opposite direction between our
lg
and largest breakpoints
Using with a custom prefix or separator
If you’re using a custom prefix
or
separator
,
you’ll need to pass them in to the extractor as well:
Integrations
tailwind-merge
fluid-tailwind
officially supports tailwind-merge via a plugin:
For best results, include it after any other tailwind-merge plugins:
Troubleshooting
Tailwind doesn’t currently provide any error reporting tools for plugins, so if a fluid utility fails, it will output an empty rule with a comment containing the reason:
You should be able to see this if you have the official IntelliSense plugin installed and hover over the class. Otherwise, you can see it if you click the location for the empty rule in your browser’s inspector.