Scroll Area

1'use client';
2
3import * as React from 'react';
4import { cn } from '../lib/cn';
5
6type ScrollAreaType = 'auto' | 'always' | 'hover' | 'scroll';
7type ScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
8type ScrollBarOrientation = 'vertical' | 'horizontal';
9
10interface ScrollAreaContextValue {
11  viewportRef: React.RefObject<HTMLDivElement | null>;
12  type: ScrollAreaType;
13  scrollHideDelay: number;
14  hovering: boolean;
15  scrolling: boolean;
16}
17
18const ScrollAreaContext = React.createContext<ScrollAreaContextValue | null>(null);
19
20function useScrollAreaContext(): ScrollAreaContextValue {
21  const context = React.use(ScrollAreaContext);
22  if (!context) throw new Error('ScrollArea parts must be used within ScrollArea');
23  return context;
24}
25
26interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
27  type?: ScrollAreaType;
28  orientation?: ScrollAreaOrientation;
29  scrollHideDelay?: number;
30  viewportRef?: React.Ref<HTMLDivElement>;
31  viewportClassName?: string;
32  label?: string;
33}
34
35const MIN_THUMB_SIZE = 18;
36
37function assignRef<T>(ref: React.Ref<T> | undefined, node: T) {
38  if (typeof ref === 'function') ref(node);
39  else if (ref) ref.current = node;
40}
41
42const ScrollAreaRoot = ({
43  type = 'hover',
44  orientation = 'vertical',
45  scrollHideDelay = 600,
46  viewportRef: externalViewportRef,
47  viewportClassName,
48  label,
49  className,
50  children,
51  onPointerEnter,
52  onPointerLeave,
53  ref,
54  ...props
55}: ScrollAreaProps & { ref?: React.Ref<HTMLDivElement> }) => {
56  const viewportRef = React.useRef<HTMLDivElement>(null);
57  const [hovering, setHovering] = React.useState(false);
58  const [scrolling, setScrolling] = React.useState(false);
59  const hideTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null);
60
61  const mergedViewportRef = React.useCallback(
62    (node: HTMLDivElement | null) => {
63      viewportRef.current = node;
64      assignRef(externalViewportRef, node);
65    },
66    [externalViewportRef],
67  );
68
69  const handleScroll = React.useCallback(() => {
70    setScrolling(true);
71    if (hideTimer.current) clearTimeout(hideTimer.current);
72    hideTimer.current = setTimeout(() => setScrolling(false), scrollHideDelay);
73  }, [scrollHideDelay]);
74
75  React.useEffect(() => {
76    return () => {
77      if (hideTimer.current) clearTimeout(hideTimer.current);
78    };
79  }, []);
80
81  const context = React.useMemo(
82    () => ({ viewportRef, type, scrollHideDelay, hovering, scrolling }),
83    [type, scrollHideDelay, hovering, scrolling],
84  );
85
86  const showVertical = orientation === 'vertical' || orientation === 'both';
87  const showHorizontal = orientation === 'horizontal' || orientation === 'both';
88
89  return (
90    <ScrollAreaContext value={context}>
91      <div
92        ref={ref}
93        data-slot="scroll-area"
94        data-orientation={orientation}
95        className={cn('relative overflow-hidden', className)}
96        onPointerEnter={(event) => {
97          onPointerEnter?.(event);
98          setHovering(true);
99        }}
100        onPointerLeave={(event) => {
101          onPointerLeave?.(event);
102          setHovering(false);
103        }}
104        {...props}
105      >
106        <div
107          ref={mergedViewportRef}
108          data-slot="scroll-area-viewport"
109          tabIndex={0}
110          role={label ? 'region' : undefined}
111          aria-label={label}
112          onScroll={handleScroll}
113          className={cn(
114            'focus-visible:ring-ring size-full [scrollbar-width:none] rounded-[inherit] outline-none focus-visible:ring-2 focus-visible:ring-inset [&::-webkit-scrollbar]:hidden',
115            showVertical ? 'overflow-y-auto' : 'overflow-y-hidden',
116            showHorizontal ? 'overflow-x-auto' : 'overflow-x-hidden',
117            viewportClassName,
118          )}
119        >
120          {children}
121        </div>
122        {showVertical && <ScrollAreaBar orientation="vertical" />}
123        {showHorizontal && <ScrollAreaBar orientation="horizontal" />}
124      </div>
125    </ScrollAreaContext>
126  );
127};
128ScrollAreaRoot.displayName = 'ScrollArea';
129
130interface ScrollAreaBarProps extends React.HTMLAttributes<HTMLDivElement> {
131  orientation?: ScrollBarOrientation;
132  forceMount?: boolean;
133}
134
135interface ThumbMetrics {
136  overflow: boolean;
137  size: number;
138  offset: number;
139}
140
141const ScrollAreaBar = ({
142  orientation = 'vertical',
143  forceMount = false,
144  className,
145  ref,
146  ...props
147}: ScrollAreaBarProps & { ref?: React.Ref<HTMLDivElement> }) => {
148  const { viewportRef, type, hovering, scrolling } = useScrollAreaContext();
149  const trackRef = React.useRef<HTMLDivElement>(null);
150  const dragRef = React.useRef<{ start: number; scroll: number } | null>(null);
151  const [metrics, setMetrics] = React.useState<ThumbMetrics>({
152    overflow: false,
153    size: 0,
154    offset: 0,
155  });
156  const [dragging, setDragging] = React.useState(false);
157  const isVertical = orientation === 'vertical';
158
159  const measure = React.useCallback(() => {
160    const viewport = viewportRef.current;
161    const track = trackRef.current;
162    if (!viewport || !track) return;
163
164    const scrollSize = isVertical ? viewport.scrollHeight : viewport.scrollWidth;
165    const clientSize = isVertical ? viewport.clientHeight : viewport.clientWidth;
166    const scrollPosition = isVertical ? viewport.scrollTop : viewport.scrollLeft;
167    const trackSize = isVertical ? track.clientHeight : track.clientWidth;
168    const overflow = scrollSize > clientSize + 1;
169
170    if (!overflow || trackSize === 0) {
171      setMetrics((previous) =>
172        previous.overflow ? { overflow: false, size: 0, offset: 0 } : previous,
173      );
174      return;
175    }
176
177    const size = Math.max(Math.round((clientSize / scrollSize) * trackSize), MIN_THUMB_SIZE);
178    const maxScroll = scrollSize - clientSize;
179    const offset = Math.round((scrollPosition / maxScroll) * (trackSize - size));
180
181    setMetrics((previous) =>
182      previous.overflow && previous.size === size && previous.offset === offset
183        ? previous
184        : { overflow: true, size, offset },
185    );
186  }, [isVertical, viewportRef]);
187
188  React.useEffect(() => {
189    const viewport = viewportRef.current;
190    if (!viewport) return;
191
192    measure();
193
194    let frame = 0;
195    const schedule = () => {
196      if (frame) return;
197      frame = requestAnimationFrame(() => {
198        frame = 0;
199        measure();
200      });
201    };
202    viewport.addEventListener('scroll', schedule, { passive: true });
203
204    let observer: ResizeObserver | undefined;
205    if (typeof ResizeObserver !== 'undefined') {
206      observer = new ResizeObserver(schedule);
207      observer.observe(viewport);
208      for (const child of Array.from(viewport.children)) observer.observe(child);
209    }
210
211    let mutations: MutationObserver | undefined;
212    if (typeof MutationObserver !== 'undefined') {
213      mutations = new MutationObserver((records) => {
214        for (const record of records) {
215          for (const node of Array.from(record.addedNodes)) {
216            if (node instanceof Element) observer?.observe(node);
217          }
218          for (const node of Array.from(record.removedNodes)) {
219            if (node instanceof Element) observer?.unobserve(node);
220          }
221        }
222        schedule();
223      });
224      mutations.observe(viewport, { childList: true });
225    }
226
227    return () => {
228      viewport.removeEventListener('scroll', schedule);
229      if (frame) cancelAnimationFrame(frame);
230      observer?.disconnect();
231      mutations?.disconnect();
232    };
233  }, [measure, viewportRef]);
234
235  const scrollTo = (position: number) => {
236    const viewport = viewportRef.current;
237    if (!viewport) return;
238    if (isVertical) viewport.scrollTop = position;
239    else viewport.scrollLeft = position;
240  };
241
242  const scrollRatio = () => {
243    const viewport = viewportRef.current;
244    const track = trackRef.current;
245    if (!viewport || !track) return 0;
246    const scrollSize = isVertical ? viewport.scrollHeight : viewport.scrollWidth;
247    const clientSize = isVertical ? viewport.clientHeight : viewport.clientWidth;
248    const trackSize = isVertical ? track.clientHeight : track.clientWidth;
249    const travel = trackSize - metrics.size;
250    return travel > 0 ? (scrollSize - clientSize) / travel : 0;
251  };
252
253  const handleThumbPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
254    event.preventDefault();
255    event.stopPropagation();
256    const viewport = viewportRef.current;
257    if (!viewport) return;
258    event.currentTarget.setPointerCapture(event.pointerId);
259    dragRef.current = {
260      start: isVertical ? event.clientY : event.clientX,
261      scroll: isVertical ? viewport.scrollTop : viewport.scrollLeft,
262    };
263    setDragging(true);
264  };
265
266  const handleThumbPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
267    const drag = dragRef.current;
268    if (!drag) return;
269    const current = isVertical ? event.clientY : event.clientX;
270    scrollTo(drag.scroll + (current - drag.start) * scrollRatio());
271  };
272
273  const handleThumbPointerUp = (event: React.PointerEvent<HTMLDivElement>) => {
274    dragRef.current = null;
275    setDragging(false);
276    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
277      event.currentTarget.releasePointerCapture(event.pointerId);
278    }
279  };
280
281  const handleTrackPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
282    const track = trackRef.current;
283    if (!track) return;
284    const rect = track.getBoundingClientRect();
285    const position = isVertical ? event.clientY - rect.top : event.clientX - rect.left;
286    scrollTo((position - metrics.size / 2) * scrollRatio());
287  };
288
289  const visible =
290    forceMount ||
291    (metrics.overflow &&
292      (type === 'always' ||
293        type === 'auto' ||
294        dragging ||
295        (type === 'hover' && (hovering || scrolling)) ||
296        (type === 'scroll' && scrolling)));
297
298  const thumbStyle = isVertical
299    ? { height: metrics.size, transform: `translateY(${metrics.offset}px)` }
300    : { width: metrics.size, transform: `translateX(${metrics.offset}px)` };
301
302  return (
303    <div
304      ref={(node) => {
305        trackRef.current = node;
306        if (typeof ref === 'function') ref(node);
307        else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
308      }}
309      data-slot="scroll-area-scrollbar"
310      data-orientation={orientation}
311      data-state={visible ? 'visible' : 'hidden'}
312      aria-hidden="true"
313      onPointerDown={handleTrackPointerDown}
314      className={cn(
315        'absolute flex touch-none transition-opacity duration-150 select-none data-[state=hidden]:pointer-events-none data-[state=hidden]:opacity-0',
316        isVertical
317          ? 'top-0 right-0 h-full w-2.5 border-l border-l-transparent p-px'
318          : 'bottom-0 left-0 h-2.5 w-full flex-col border-t border-t-transparent p-px',
319        className,
320      )}
321      {...props}
322    >
323      <div
324        data-slot="scroll-area-thumb"
325        data-dragging={dragging ? '' : undefined}
326        onPointerDown={handleThumbPointerDown}
327        onPointerMove={handleThumbPointerMove}
328        onPointerUp={handleThumbPointerUp}
329        onPointerCancel={handleThumbPointerUp}
330        style={thumbStyle}
331        className={cn(
332          'bg-border hover:bg-muted-foreground/50 data-[dragging]:bg-muted-foreground/60 relative rounded-full transition-colors',
333          isVertical ? 'w-full' : 'h-full',
334        )}
335      />
336    </div>
337  );
338};
339ScrollAreaBar.displayName = 'ScrollAreaBar';
340
341const ScrollArea = Object.assign(ScrollAreaRoot, {
342  Bar: ScrollAreaBar,
343});
344
345export { ScrollArea, useScrollAreaContext };
346export type { ScrollAreaProps, ScrollAreaBarProps, ScrollAreaType, ScrollAreaOrientation };