tw-fade: Pure CSS Scroll-Driven Edge Masking

tw-fade is a specialized Tailwind CSS v4 Plugin designed to implement elegant, scroll-driven edge masking. Developed by one of the architects behind tw-shimmer (which boasts over 475k weekly npm downloads), this tool brings a sophisticated visual polish to scrollable containers.

🚀 Getting Started

To integrate this into your project, run the following command:

npm i tw-fade

Quick Setup Checklist

• Install tw-fade via npm.
• Add the plugin to your tailwind.config.js (v4).
• Apply axis utilities (e.g., fade-y) to your scroll container.
• Fine-tune the fade-size and fade-range.

---

🎨 The Art of "Peripheral Impermanence"

Rather than abrupt clipping, tw-fade introduces a concept of peripheral impermanence. This means content doesn't just stop; it gracefully dissolves into the background.

"Eased alpha ramps dissolve content into the surface instead of ending on a clipped line."

The Vocabulary of Fading

The library evokes a wide array of visual sensations. Below is a mapping of the atmospheric effects achieved through these masks:

Other evocative states include: Penumbra, Crepuscular, Involution, Adumbrate, Shadow, Silhouette, and Deliquescence.

---

🛠 Technical Implementation

Composable Utilities

You can mix and match utilities directly on your scroll container to achieve the desired look:

1. Axis: fade-x, fade-y, fade-xy, fade-t (top), fade-r (right).
2. Size: fade-size-lg, fade-size-2xl.
3. Range: fade-range-md, fade-range-2xl.

How it Works (Logic Flow)

The masking is scroll-aware. The fades are not static; they appear only when there is actual content remaining to be scrolled.

The Mathematics of the Fade

The transition is governed by an eased alpha gradient, which can be represented as a function of the distance from the edge $x$:

$\alpha(x) = \text{smoothstep}(\text{range}_{start}, \text{range}_{end}, x)$

This ensures that the transition from opaque to transparent is non-linear and visually organic.

---

💻 Usage Example

This feed has a hard edge. $\rightarrow$ Add fade-y to the scroll area.

You don't need an extra wrapper element; the utilities compose directly on the container.

<!-- Example: A vertical scroll area with a large fade and medium range -->
<div class="overflow-y-auto fade-y fade-size-2xl fade-range-md">
  <!-- Your long content here -->
  <p>The bottom fade clears as the newest message stays clear.</p>
</div>

Note: The system works on any background. In demo environments, JS (like demo-controls) may be used to point the stage rectangle at a specific background ID for previewing.