# useScrollEdges

> A React scroll shadow and fade hook: knows which edges of a scroll container hide more content and fades them with a mask.

- Type: React hook (Hooks & Utilities)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add use-scroll-edges`
- Docs: https://wingo-ui.com/components/use-scroll-edges

## Interaction

Scroll the notification list: the top fades in as content slides under the header, a hairline appears below the title, and the bottom fade melts away as you reach the end. Swipe the category rail sideways: the edges fade the same way and the arrow buttons (on desktop) hide at each end.

## Installation

```bash
npx wingo-ui@latest add use-scroll-edges
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/use-scroll-edges.json`

Files:

- `hooks/use-scroll-edges.ts`

## Usage

```tsx
import { fadeMaskStyle, useScrollEdges } from "@/hooks/use-scroll-edges"
import { cn } from "@/lib/utils"

export function Notifications({ items }: { items: string[] }) {
  const { ref, edges } = useScrollEdges<HTMLUListElement>()

  return (
    <section className="flex max-h-80 flex-col">
      <h2 className={cn("px-4 py-3 text-[15px] font-semibold", edges.top && "border-b border-foreground/10")}>Notifications</h2>
      <ul ref={ref} style={fadeMaskStyle("y")} className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4">
        {items.map((item) => (
          <li key={item} className="py-3 text-sm">{item}</li>
        ))}
      </ul>
    </section>
  )
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fade?` | `number` | `24` | useScrollEdges(options?): the largest fade in px. The hook writes --fade-top, --fade-bottom, --fade-left and --fade-right on the element, each growing with the distance to its edge, so a fade eases out as you reach the end instead of popping. |
| `threshold?` | `number` | `1` | Distance in px from an edge that still counts as being at it (absorbs sub-pixel scroll positions). |
| `disabled?` | `boolean` | `false` | Stops measuring; the fades stay at their last size. |
| `returns?` | `{ ref: RefCallback<T>; edges: ScrollEdges; overflow: { x: boolean; y: boolean } }` |  | ref goes on the scrolling element (a plain overflow div or a Radix ScrollArea viewport). edges says where more content lies ({ top, bottom, left, right }) and overflow whether it scrolls at all; both re-render only when a value flips, never per scroll frame. Handles RTL. |

## Parts

### ScrollEdges (type)

{ top: boolean; bottom: boolean; left: boolean; right: boolean }: where more content lies.

### ScrollAxis (type)

"x" | "y" | "both", the axis fadeMaskStyle fades.

### UseScrollEdgesOptions (type)

The options object: fade, threshold and disabled.

### UseScrollEdgesResult (type)

The return value: { ref, edges, overflow }.

### fadeMaskStyle (function)

A mask-image style driven by the vars above. Spread it into the same element's style. It needs no background color, so it works on any surface in both themes. Signature: (axis?: "x" | "y" | "both") => CSSProperties.

## Examples

- **Read to the end to accept**: edges.bottom keeps the Accept button locked until the reader scrolls to the last line.
- **Dividers only when needed**: The header and footer hairlines appear only while content scrolls under them.

## See also

- [Scroll Area](https://wingo-ui.com/components/scroll-area) ([Markdown](https://wingo-ui.com/components/scroll-area.md))
- [useScrollState](https://wingo-ui.com/components/use-scroll-state) ([Markdown](https://wingo-ui.com/components/use-scroll-state.md))
- [useOverflowItems](https://wingo-ui.com/components/use-overflow-items) ([Markdown](https://wingo-ui.com/components/use-overflow-items.md))
- [Dialog](https://wingo-ui.com/components/dialog) ([Markdown](https://wingo-ui.com/components/dialog.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))

---

Canonical: https://wingo-ui.com/components/use-scroll-edges
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt