# scroll-fade

Utilities for adding a fade effect to the edges of a scroll container.

Source: https://webjs.dev/ui/docs/utils/scroll-fade

```ts
import { html } from '@webjsdev/core';

export default function ScrollFadeDemo() {
  return html`
    <div class="mx-auto w-full max-w-xs overflow-hidden rounded-2xl border">
      <div class="h-72 scroll-fade no-scrollbar overflow-y-auto">
        <div class="flex flex-col gap-1.5 p-1.5">
          ${Array.from({ length: 12 }, (_, index) => html`
            <div class="rounded-lg bg-muted px-3 py-2.5 text-sm">Item ${index + 1}</div>
          `)}
        </div>
      </div>
    </div>
  `;
}
```

## Installation

`scroll-fade` ships in `shadcn-tailwind.css`, the kit's shared Tailwind stylesheet of utilities and variants. It lives in the `@webjsdev/ui` package at `packages/registry/styles/shadcn-tailwind.css`, which a WebJs app has through the WebJs CLI. `webjs ui init` does not copy it into your app yet, so copy it next to your stylesheet:

```bash
cp node_modules/@webjsdev/ui/packages/registry/styles/shadcn-tailwind.css styles/
```

Then import it after Tailwind in your global CSS file:

```css
@import "tailwindcss";
@import "./shadcn-tailwind.css";
```

The same file carries the `shimmer` and `no-scrollbar` utilities and the `data-open` and `data-checked` variants the kit's styles use.

## Usage

| Class | Styles |
| --- | --- |
| `scroll-fade` | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));` `animation-timeline: scroll(self y);` |
| `scroll-fade-y` | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));` `animation-timeline: scroll(self y);` |
| `scroll-fade-x` | `mask-image: var(--scroll-fade-mask, var(--scroll-fade-inline));` `animation-timeline: scroll(self inline);` |
| `scroll-fade-t` | Fade mask on the top edge. `animation-timeline: scroll(self y);` |
| `scroll-fade-b` | Fade mask on the bottom edge. `animation-timeline: scroll(self y);` |
| `scroll-fade-l` | Fade mask on the left edge. `animation-timeline: scroll(self x);` |
| `scroll-fade-r` | Fade mask on the right edge. `animation-timeline: scroll(self x);` |
| `scroll-fade-s` | Fade mask on the start edge, mirrors in RTL. `animation-timeline: scroll(self inline);` |
| `scroll-fade-e` | Fade mask on the end edge, mirrors in RTL. `animation-timeline: scroll(self inline);` |
| `scroll-fade-<number>` | `--scroll-fade-size: calc(var(--spacing) * <number>);` |
| `scroll-fade-[<value>]` | `--scroll-fade-size: <value>;` |
| `scroll-fade-{t,b,s,e}-<number>` | `--scroll-fade-{t,b,s,e}-size: calc(var(--spacing) * <number>);` |
| `scroll-fade-{t,b,s,e}-[<value>]` | `--scroll-fade-{t,b,s,e}-size: <value>;` |
| `scroll-fade-none` | `--scroll-fade-mask: none;` |

Add `scroll-fade` or `scroll-fade-y` to the scroll container, i.e. the element that has `overflow-y-auto`.

```html
<div class="scroll-fade overflow-y-auto">...</div>
```

The fade is scroll-aware and tracks the scroll position:

- At rest, the top edge is crisp and the bottom edge fades to hint at more content.
- As you scroll, a fade appears at the top and both edges stay faded mid-scroll.
- At the end, the bottom edge sharpens to show you have reached the last item.

The fade is applied with `mask-image`, so it dissolves the content itself rather than overlaying a color. The mask uses a linear fade from transparent to black, so it adapts to any background without configuration. If your scroll area sits inside a card, put the background and border on a wrapper and `scroll-fade` on the inner scroller, so the fade dissolves the content and not the card.

The [Scroll Area](https://webjs.dev/ui/docs/components/scroll-area) and [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller) components can use `scroll-fade` on their scrollable viewport.

## No Overflow, No Fade

If the content does not overflow, no fade is shown. You can apply `scroll-fade` to any list without checking whether it scrolls.

```ts
import { html } from '@webjsdev/core';

export default function ScrollFadeOverflow() {
  return html`
    <div class="mx-auto w-full max-w-xs overflow-hidden rounded-2xl border">
      <div class="scroll-fade no-scrollbar overflow-y-auto">
        <div class="flex flex-col gap-1.5 p-1.5">
          ${Array.from({ length: 3 }, (_, index) => html`
            <div class="rounded-lg bg-muted px-3 py-2.5 text-sm">Item ${index + 1}</div>
          `)}
        </div>
      </div>
    </div>
  `;
}
```

## Horizontal Scrolling

Use `scroll-fade-x` on containers that scroll horizontally, i.e. the element that has `overflow-x-auto`.

```ts
import { html } from '@webjsdev/core';

const tags = [
  'Design',
  'Engineering',
  'Marketing',
  'Product',
  'Research',
  'Sales',
  'Support',
  'Operations',
  'Finance',
  'Legal',
  'People',
  'Security',
];

export default function ScrollFadeHorizontal() {
  return html`
    <div class="mx-auto w-full max-w-xs overflow-hidden rounded-2xl border">
      <div class="scroll-fade-x no-scrollbar overflow-x-auto">
        <div class="flex w-max gap-1.5 p-1.5">
          ${tags.map((tag) => html`
            <div class="shrink-0 rounded-lg bg-muted px-3 py-2.5 text-sm">${tag}</div>
          `)}
        </div>
      </div>
    </div>
  `;
}
```

```html
<div class="flex scroll-fade-x overflow-x-auto">...</div>
```

The horizontal fade is direction-aware. In RTL layouts, the crisp edge and the fade follow the reading direction with no extra classes needed. `scroll-fade-<number>` and `scroll-fade-none` work the same for both axes.

## Edge Fades

Use edge utilities when only one edge should track the scroll position.

```ts
import { html } from '@webjsdev/core';

const items = [
  'Inbox triage',
  'Design review',
  'API contract',
  'QA pass',
  'Launch notes',
  'Metrics follow-up',
];

const tags = [
  'Design',
  'Engineering',
  'Marketing',
  'Product',
  'Research',
  'Sales',
  'Support',
  'Operations',
];

function scrollFadeEdgeItems() {
  return html`
    <div class="flex flex-col gap-1.5 p-1.5">
      ${items.map((item) => html`<div class="rounded-lg bg-muted px-3 py-2.5 text-sm">${item}</div>`)}
    </div>
  `;
}

function scrollFadeEdgeTags() {
  return html`
    <div class="flex w-max gap-1.5 p-1.5">
      ${tags.map((tag) => html`<div class="shrink-0 rounded-xl bg-muted px-4 py-2.5 text-sm">${tag}</div>`)}
    </div>
  `;
}

export default function ScrollFadeEdge() {
  return html`
    <div class="mx-auto flex max-w-xs min-w-0 flex-col gap-6">
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-36 scroll-fade-t no-scrollbar overflow-y-auto">${scrollFadeEdgeItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-t</p>
      </div>
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-36 scroll-fade-b no-scrollbar overflow-y-auto">${scrollFadeEdgeItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-b</p>
      </div>
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="scroll-fade-s no-scrollbar overflow-x-auto">${scrollFadeEdgeTags()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-s</p>
      </div>
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="scroll-fade-e no-scrollbar overflow-x-auto">${scrollFadeEdgeTags()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-e</p>
      </div>
    </div>
  `;
}
```

```html
<div class="scroll-fade-b overflow-y-auto">...</div>
```

The edge utilities are scroll-aware. Start edges fade in after you scroll away from the start, and end edges fade out when you reach the end. Use `scroll-fade-t`, `scroll-fade-b`, `scroll-fade-l`, and `scroll-fade-r` for physical edges. Use `scroll-fade-s` and `scroll-fade-e` for logical inline edges that mirror in RTL.

## Fade Size

The fade depth defaults to `12%` of the container, capped at `40px` so tall scrollers stay subtle. Use `scroll-fade-<number>` to set a fixed size on the spacing scale instead, the same way `scroll-mt-<number>` works.

```ts
import { html } from '@webjsdev/core';

function scrollFadeSizeItems() {
  return html`
    <div class="flex flex-col gap-1.5 p-1.5">
      ${Array.from({ length: 8 }, (_, index) => html`
        <div class="rounded-lg bg-muted px-3 py-2.5 text-sm">Item ${index + 1}</div>
      `)}
    </div>
  `;
}

export default function ScrollFadeSize() {
  return html`
    <div class="mx-auto flex w-full max-w-xs flex-col gap-6">
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-48 scroll-fade no-scrollbar overflow-y-auto scroll-fade-4">${scrollFadeSizeItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-4</p>
      </div>
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-48 scroll-fade no-scrollbar overflow-y-auto scroll-fade-24">${scrollFadeSizeItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade-24</p>
      </div>
    </div>
  `;
}
```

```html
<div class="scroll-fade overflow-y-auto scroll-fade-24">...</div>
```

For one-off values, use an arbitrary length or percentage:

```html
<div class="scroll-fade overflow-y-auto scroll-fade-[15%]">...</div>
```

To fade opposite edges by different amounts, use the per-edge modifiers `scroll-fade-t-<number>`, `scroll-fade-b-<number>`, `scroll-fade-s-<number>`, and `scroll-fade-e-<number>`. They override `scroll-fade-<number>` on the edge they target and accept arbitrary values too.

```html
<div class="scroll-fade overflow-y-auto scroll-fade-b-8 scroll-fade-t-2">
  ...
</div>
```

Use the logical `s`/`e` modifiers for horizontal scrollers so the sizes mirror in RTL.

The fade eases in and out over a fixed scroll distance rather than appearing instantly. That distance is the `--scroll-fade-reveal` variable, `96px` by default and independent of the fade depth. Lower it for a snappier reveal or raise it for a more gradual one:

```html
<div class="scroll-fade overflow-y-auto [--scroll-fade-reveal:64px]">
  ...
</div>
```

## Disabling the Fade

Use `scroll-fade-none` to remove the fade. It works in any class order, so the typical use is responsive or stateful:

```html
<div class="scroll-fade overflow-y-auto md:scroll-fade-none">
  ...
</div>
```

```ts
import { html } from '@webjsdev/core';

function scrollFadeNoneItems() {
  return html`
    <div class="flex flex-col gap-1.5 p-1.5">
      ${Array.from({ length: 8 }, (_, index) => html`
        <div class="rounded-lg bg-muted px-3 py-2.5 text-sm">Item ${index + 1}</div>
      `)}
    </div>
  `;
}

export default function ScrollFadeNone() {
  return html`
    <div class="mx-auto flex w-full max-w-xs min-w-0 flex-col gap-6">
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-48 scroll-fade no-scrollbar overflow-y-auto">${scrollFadeNoneItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade</p>
      </div>
      <div class="flex flex-col gap-3">
        <div class="overflow-hidden rounded-2xl border">
          <div class="h-48 scroll-fade no-scrollbar overflow-y-auto scroll-fade-none">${scrollFadeNoneItems()}</div>
        </div>
        <p class="text-center font-mono text-xs text-muted-foreground">scroll-fade scroll-fade-none</p>
      </div>
    </div>
  `;
}
```

## Fallback

The scroll-aware behavior is implemented with [CSS scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scroll-driven_animations), with no JavaScript and no scroll listeners. In browsers that do not support scroll-driven animations, `scroll-fade` falls back to a static fade on both edges, and edge utilities fall back to a static fade on the selected edge.

Since the mask is applied to the scroll container itself, a visible scrollbar fades with the content at the edges. Pair `scroll-fade` with `no-scrollbar`, which ships in the same file, if you want to hide the scrollbar entirely.

## RTL

To enable RTL support in WebJs UI, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

`scroll-fade-x` follows the reading direction. At rest, the start edge is crisp and the end edge fades. In RTL layouts that means a crisp right edge and a fade on the left, mirrored from LTR.

```ts
import { html } from '@webjsdev/core';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      design: 'Design',
      engineering: 'Engineering',
      marketing: 'Marketing',
      product: 'Product',
      research: 'Research',
      sales: 'Sales',
      support: 'Support',
      operations: 'Operations',
      finance: 'Finance',
      legal: 'Legal',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      design: 'تصميم',
      engineering: 'هندسة',
      marketing: 'تسويق',
      product: 'منتج',
      research: 'أبحاث',
      sales: 'مبيعات',
      support: 'دعم',
      operations: 'عمليات',
      finance: 'مالية',
      legal: 'قانوني',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      design: 'עיצוב',
      engineering: 'הנדסה',
      marketing: 'שיווק',
      product: 'מוצר',
      research: 'מחקר',
      sales: 'מכירות',
      support: 'תמיכה',
      operations: 'תפעול',
      finance: 'כספים',
      legal: 'משפטי',
    },
  },
};

export default function ScrollFadeRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div class="mx-auto w-full max-w-xs overflow-hidden rounded-2xl border" dir=${dir} lang=${lang}>
      <div class="scroll-fade-x no-scrollbar overflow-x-auto">
        <div class="flex w-max gap-1.5 p-1.5">
          ${Object.values(t).map((tag) => html`
            <div class="shrink-0 rounded-lg bg-muted px-3 py-2.5 text-sm">${tag}</div>
          `)}
        </div>
      </div>
    </div>
  `;
}
```
