When to use
- A fixed-height list inside a card, panel or sidebar: an activity feed, a list of members, a log.
- A row of chips or filters that scrolls sideways on narrow screens:
orientation="horizontal". - Anywhere the browser's default scrollbar would look out of place or take up width.
When not to use
- The page itself: let the document scroll natively.
- Content that fits: a Scroll Area with nothing to scroll adds a wrapper and nothing else.
- Very long lists of thousands of rows: it renders every child, so pair it with a virtualiser or paginate with Pagination.
Scroll Area vs the shadcn/ui Scroll Area
shadcn/ui's Scroll Area is a styled wrapper around a headless scroll area: it gives you a themed scrollbar, and you add a separate horizontal ScrollBar when content scrolls sideways. Eased's Scroll Area is an alternative built on the same idea, a native scroller with a custom bar, plus the details that usually get added by hand:
| shadcn/ui Scroll Area | Eased Scroll Area | |
|---|---|---|
| Scrolling | Native | Native |
| Horizontal and both directions | Add a horizontal ScrollBar | orientation="horizontal" or "both" |
| Edge fades | Not included | Fade only where there is more to scroll (fade, 20px by default) |
| Named region | Add it yourself | aria-label makes the viewport a named region |
Eased's version also:
- hides the bar at rest and shows it while you scroll or point at it
- draws a 4px pill inside a 10px hit zone, so it is easy to grab, and thickens it to 6px under the pointer
- draws the focus ring inset, so the clipped viewport can't hide it
- keeps the page from scrolling once the area reaches its end
Install it next to the shadcn/ui component, or replace it: imports come from @/components/eased/scroll-area/scroll-area, so both can live in the same project while you switch over.
FAQ
How do I make a custom scrollbar in React?
Keep the browser's native scrolling and hide its scrollbar, then draw your own thumb sized and positioned from the scroll position. Scroll Area does this on Base UI's Scroll Area, so trackpads, touch, keyboard scrolling and find-in-page keep working.
How do I add fade edges to a scrolling list?
Set fade on Scroll Area to the size of the fade in pixels. Each edge fades only while there is more content to scroll in that direction, so the top edge stays sharp until you scroll down.
How do I make a horizontal scroll area?
Set orientation="horizontal" and give the content w-max in contentClassName, so it keeps its natural width and scrolls sideways.
Is a custom scrollbar accessible?
It can be, as long as scrolling stays native. Name the region with aria-label so it is announced when it receives focus, and make sure the focus ring is visible. Keyboard users scroll it with the arrow keys, Page Up, Page Down, Home and End.
Installation
pnpm dlx shadcn add https://eased.dev/r/scroll-area.jsonnpx shadcn add https://eased.dev/r/scroll-area.jsonyarn dlx shadcn add https://eased.dev/r/scroll-area.jsonbunx --bun shadcn add https://eased.dev/r/scroll-area.jsonThe command adds Scroll Area, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add @base-ui/reactnpm install @base-ui/reactyarn add @base-ui/reactbun add @base-ui/reactAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/scroll-area/scroll-area.tsxTSX "use client";import { ScrollArea as Base } from "@base-ui/react/scroll-area";import type { CSSProperties, ReactNode, Ref } from "react";import { scrollFadeMask, type FadeAxis } from "../_primitives/scroll-fade/scroll-fade";export type ScrollAreaProps = { children: ReactNode; /** Which way it scrolls. "both" draws both bars and fades all four edges. Default "vertical". */ orientation?: "vertical" | "horizontal" | "both"; /** Edge feather in px, drawn only while there is more to scroll that way; 0 turns it off. Default 20. */ fade?: number; /** Classes for the root: size it here (`h-64`, `max-h-80`, `flex-1 min-h-0`). */ className?: string; /** Classes for the content wrapper: put padding here so it scrolls with the content. */ contentClassName?: string; /** The scrolling element, for `scrollTo`, scroll-linked effects or a Progressive Blur. */ viewportRef?: Ref<HTMLDivElement>; /** Accessible name for the scrollable region, which is a keyboard tab stop when it overflows. */ "aria-label"?: string; "aria-labelledby"?: string; style?: CSSProperties;};const AXIS: Record<NonNullable<ScrollAreaProps["orientation"]>, FadeAxis> = { vertical: "y", horizontal: "x", both: "both" };// The bar is a 10px hit zone; the visible pill is 6px and drawn at 2/3 until the pointer is on// the bar, so it thickens under the pointer (scale, not width, so it stays on the compositor).const bar = "group/bar flex touch-none p-0.5 opacity-0 select-none pointer-events-none transition-opacity duration-(--eased-duration-slow) ease-standard data-hovering:pointer-events-auto data-hovering:opacity-100 data-hovering:duration-(--eased-duration-fast) data-scrolling:pointer-events-auto data-scrolling:opacity-100 data-scrolling:duration-(--eased-duration-instant) reduced:transition-none";const pill = "rounded-pill bg-line-strong transition-[scale,background-color] duration-(--eased-duration-fast) ease-standard group-active/bar:bg-text-muted group-active/bar:scale-100 [@media(hover:hover)_and_(pointer:fine)]:group-hover/bar:scale-100 [@media(hover:hover)_and_(pointer:fine)]:group-hover/bar:bg-text-muted reduced:transition-none";/** * A native scroller with Eased's overlay scrollbar and edge fades. Base UI owns the scrolling, * the thumb drag and the keyboard (the viewport is a tab stop that arrow keys scroll); Eased * draws a thin themed pill that appears while scrolling or hovering and thickens under the * pointer, and feathers each edge only while there is content past it. */export function ScrollArea({ children, orientation = "vertical", fade = 20, className = "", contentClassName = "", viewportRef, style, ...aria}: ScrollAreaProps) { const vertical = orientation !== "horizontal"; const horizontal = orientation !== "vertical"; return ( <Base.Root style={style} className={`relative min-h-0 min-w-0 overflow-hidden -outline-offset-2 has-[[data-eased-viewport]:focus-visible]:outline-2 has-[[data-eased-viewport]:focus-visible]:outline-focus ${className}`} > <Base.Viewport ref={viewportRef} data-eased-viewport="" {...aria} role={aria["aria-label"] || aria["aria-labelledby"] ? "region" : undefined} style={{ ...(fade > 0 && scrollFadeMask(AXIS[orientation], fade)), // Base UI sets overflow: scroll inline; lock the axis this area does not scroll. ...(!vertical && { overflowY: "hidden" }), ...(!horizontal && { overflowX: "hidden" }), }} className="size-full max-h-[inherit] overscroll-contain outline-none" > {/* Base UI sets min-width: fit-content inline; a vertical-only area must shrink to the viewport instead, or wide rows push their trailing column out of view. */} <Base.Content style={horizontal ? undefined : { minWidth: 0 }} className={contentClassName}> {children} </Base.Content> </Base.Viewport> {vertical && ( <Base.Scrollbar orientation="vertical" className={`${bar} w-2.5 justify-end`}> <Base.Thumb className="flex w-full justify-end"> <span className={`${pill} h-full w-1.5 origin-right scale-x-[0.67]`} /> </Base.Thumb> </Base.Scrollbar> )} {horizontal && ( <Base.Scrollbar orientation="horizontal" className={`${bar} h-2.5 flex-col justify-end`}> <Base.Thumb className="flex h-full flex-col justify-end"> <span className={`${pill} h-1.5 w-full origin-bottom scale-y-[0.67]`} /> </Base.Thumb> </Base.Scrollbar> )} {orientation === "both" && <Base.Corner />} </Base.Root> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
import { ScrollArea } from "@/components/eased/scroll-area/scroll-area";export function ActivityFeed({ events }: { events: { id: string; text: string }[] }) { return ( <ScrollArea className="h-72" contentClassName="px-4 py-2" aria-label="Activity"> <ul> {events.map((e) => ( <li key={e.id} className="py-2 text-ui">{e.text}</li> ))} </ul> </ScrollArea> );}Size the root with className (h-72, max-h-80, or flex-1 min-h-0 in a flex column), and put padding in contentClassName so it scrolls with the content.
Examples
Horizontal
A row of filter chips that scrolls sideways. Give the content w-max so it keeps its natural width.
<ScrollArea orientation="horizontal" fade={24} aria-label="Filters" contentClassName="w-max px-4 py-2"> <ToggleGroup variant="chips" multiple aria-label="Event types" defaultValue={["deploys"]}> <ToggleGroupItem value="deploys">Deploys</ToggleGroupItem> <ToggleGroupItem value="incidents">Incidents</ToggleGroupItem> <ToggleGroupItem value="comments">Comments</ToggleGroupItem> </ToggleGroup></ScrollArea>Scrolling to the latest item
viewportRef reaches the scrolling element, for scrollTo or scroll-linked effects.
const viewport = useRef<HTMLDivElement>(null);useEffect(() => { viewport.current?.scrollTo({ top: viewport.current.scrollHeight, behavior: "smooth" });}, [messages.length]);<ScrollArea viewportRef={viewport} className="min-h-0 flex-1" aria-label="Messages">…</ScrollArea>API reference
ScrollArea
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "both" | "vertical" | Which way it scrolls. The other axis is locked; "both" draws both bars and fades all four edges. |
fade | number | 20 | Edge feather in px, drawn only while there is more to scroll that way. 0 turns it off. |
className | string | "" | Classes for the root. Size it here. |
contentClassName | string | "" | Classes for the content wrapper. Put padding here. |
viewportRef | Ref<HTMLDivElement> | The scrolling element. | |
aria-label / aria-labelledby | string | Names the scrollable region. | |
style | CSSProperties | Root style. | |
children | ReactNode |
Keyboard
| Key | Action |
|---|---|
Tab | Focuses the scrolling region while it overflows. |
↑ ↓ ← → | Scroll the focused region. |
Page Up / Page Down, Home / End | Scroll by a page, or to either end. |
These are the browser's own keys for a focused scroller.
Accessibility
- With
aria-labeloraria-labelledby, the viewport becomes a namedrole="region". Name it whenever it scrolls, because it is a tab stop. - The focus ring is drawn inset on the root, because the faded, clipped viewport would hide an outline outside it.
- Scrolling stays native, so trackpads, touch, screen readers and find-in-page work as usual;
overscroll-behavior: containkeeps the page from scrolling once the area reaches its end. - In a vertical area, wide content shrinks to the viewport instead of pushing its last column out of view.
Motion
The scrollbar is hidden at rest. It appears in 100ms while you scroll and in 150ms when the pointer is over it, and fades away over 300ms. The thumb is a 4px pill in a 10px hit zone that thickens to 6px and darkens under the pointer or while dragged, over 150ms, scaling rather than changing width. Each edge feathers in only as far as there is content past it, so a list at rest at its top shows no top fade at all and the fade grows as you scroll away. Reduced motion: the bar and the pill change without transitions.
Notes for AI
Use ScrollArea for any bounded region that scrolls inside a page: size it with className, pad it with contentClassName, and always give it an aria-label. Use orientation="horizontal" with w-max content for chip rows.
Do not put padding or a fixed height on the content wrapper instead of the root, and do not add your own scrollbar styling or gradient overlays for the edges: the fade is a mask that already tracks the scroll position.
Related components
- Progressive Blur Effect: a scroll-linked blur at an edge, driven by
viewportRef. - Animated Toggle Group: its chips variant is the row you would scroll sideways.
- Animated Accordion