tailwindcss-scroll-mask

tailwindcss-scroll-mask

Scroll-driven edge fade utilities for Tailwind CSS v4.

Live demo

Install

npm i -D tailwindcss-scroll-mask

In your CSS entry (the file where you @import "tailwindcss"):

@import 'tailwindcss';
@import 'tailwindcss-scroll-mask';

Usage

Class	Effect	Default size
scroll-mask	all four sides	1rem
scroll-mask-<n>	all four sides	--spacing(n) (e.g. scroll-mask-4 → 1rem)
scroll-mask-x	left + right	1rem
scroll-mask-x-<n>	left + right	--spacing(n)
scroll-mask-y	top + bottom	1rem
scroll-mask-y-<n>	top + bottom	--spacing(n)
scroll-mask-l[-<n>]	left only	1rem / --spacing(n)
scroll-mask-r[-<n>]	right only	1rem / --spacing(n)
scroll-mask-t[-<n>]	top only	1rem / --spacing(n)
scroll-mask-b[-<n>]	bottom only	1rem / --spacing(n)

All -<n> forms also accept [<length>], [<percentage>], or arbitrary values:

<div class="scroll-mask-x-[11px]">…</div>
<div class="scroll-mask-y-[10%]">…</div>
<div class="scroll-mask-l-(--gap)">…</div>

Composition

Side and axis utilities compose freely:

<!-- All four sides, l/r 2 units, t/b 4 units -->
<div class="scroll-mask-x-2 scroll-mask-y-4">…</div>

<!-- All sides 4u, but disable left -->
<div class="scroll-mask-4 scroll-mask-l-0">…</div>

<!-- Only top + left -->
<div class="scroll-mask-l scroll-mask-t">…</div>

Responsive / state variants

Standard Tailwind variant prefixes work as expected:

<div class="scroll-mask-y sm:scroll-mask-y-2 md:scroll-mask">…</div>

Examples

Horizontal tab strip

<nav class="flex scroll-mask-x-12 gap-1 overflow-x-auto p-1.5">
	<button>Tab 1</button>
	<button>Tab 2</button>
	<button>Tab 3</button>
	<!-- … -->
</nav>

Vertical chat / list

<ul class="h-96 scroll-mask-y overflow-y-auto">
	<li>…</li>
	<li>…</li>
</ul>

Fade only at the bottom (e.g. read-more teaser)

<div class="max-h-32 scroll-mask-b-16 overflow-y-auto">
	<p>Long text…</p>
</div>

How it works

The plugin registers four @property slots (--tw-scroll-mask-{l,r,t,b}) each defaulting to an identity linear-gradient(#fff, #fff) (a "do nothing" mask layer). Every utility:

1. Sets mask-image to the four slots layered together with mask-composite: intersect.
2. Activates the relevant slot(s) by replacing the identity with a real fade gradient.
3. Drives the gradient's stop position via a scroll-driven @keyframes whose animation-range is length-based — so the transition zone always equals the fade size in pixels, regardless of scroller length.

Because each utility writes only the slots it owns, classes compose additively without cascade tricks.

This is the same composition pattern Tailwind CSS v4 itself uses for its built-in mask-l-from-* / mask-r-from-* / etc. utilities.

Customization

Per-element override

Override a single side's gradient or size without modifying the plugin:

<!-- Custom left gradient -->
<div
	class="scroll-mask-l"
	style="--tw-scroll-mask-l: linear-gradient(to right, transparent, blue 1rem, blue);"
>
	…
</div>

<!-- Per-side asymmetric size -->
<div class="scroll-mask" style="--tw-scroll-mask-l-size: 0.5rem; --tw-scroll-mask-r-size: 3rem;">
	…
</div>

Reduced motion

Wrapped in @media (prefers-reduced-motion: no-preference). Users with reduced-motion preference get no fade at all (the element renders unmasked).

Browser support

Relies on scroll-driven animations (animation-timeline: scroll()).

In unsupported browsers the fade is suppressed via @supports and content remains fully scrollable and visible. If you need a static fallback, layer your own linear-gradient mask outside this plugin.

Credits

• Composition pattern adapted from Tailwind CSS v4's mask-* utilities.
• Original scroll-driven mask idea: @linuz90's gist.

License

MIT