[scroll area] Prevent scroll snapping while dragging the thumb (#5259)

Author: atomiks

docs/src/app/(private)/experiments/scroll-area/scroll-area-snap.module.css

@@ -0,0 +1,62 @@
+.Container {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+  padding: 2rem;
+}
+
+.Heading {
+  margin: 0 0 0.5rem;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.ScrollAreaRoot {
+  width: 400px;
+}
+
+.ScrollAreaViewport {
+  width: 100%;
+  scroll-snap-type: x mandatory;
+}
+
+.NativeScroller {
+  width: 400px;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+}
+
+.Row {
+  display: flex;
+}
+
+.Item {
+  box-sizing: border-box;
+  flex-shrink: 0;
+  display: grid;
+  place-items: center;
+  width: 200px;
+  height: 120px;
+  scroll-snap-align: start;
+  background: #f5f5f5;
+  font-size: 2rem;
+
+  &:nth-child(even) {
+    background: #e0e0e0;
+  }
+}
+
+.ScrollAreaScrollbar {
+  display: flex;
+  /* Column direction so the thumb's `flex` stretches it across the track's
+     thickness, leaving its width to `--scroll-area-thumb-width`. */
+  flex-direction: column;
+  height: 10px;
+  background: rgb(0 0 0 / 0.05);
+}
+
+.ScrollAreaThumb {
+  flex: 1;
+  border-radius: 20px;
+  background: rgb(0 0 0 / 0.5);
+}

docs/src/app/(private)/experiments/scroll-area/scroll-area-snap.tsx

@@ -0,0 +1,47 @@
+'use client';
+import { ScrollArea } from '@base-ui/react/scroll-area';
+import styles from './scroll-area-snap.module.css';
+
+const ITEMS = Array.from({ length: 10 }, (_, index) => index + 1);
+
+function Items() {
+  return (
+    <div className={styles.Row}>
+      {ITEMS.map((item) => (
+        <div key={item} className={styles.Item}>
+          {item}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function ScrollAreaSnap() {
+  return (
+    <div className={styles.Container}>
+      <p>
+        Dragging the thumb should track the pointer continuously and only snap to the nearest item
+        once the pointer is released, matching the native scroller below.
+      </p>
+
+      <div>
+        <h2 className={styles.Heading}>Scroll area</h2>
+        <ScrollArea.Root className={styles.ScrollAreaRoot}>
+          <ScrollArea.Viewport className={styles.ScrollAreaViewport}>
+            <Items />
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar orientation="horizontal" className={styles.ScrollAreaScrollbar}>
+            <ScrollArea.Thumb className={styles.ScrollAreaThumb} />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>
+      </div>
+
+      <div>
+        <h2 className={styles.Heading}>Native scroller</h2>
+        <div className={styles.NativeScroller}>
+          <Items />
+        </div>
+      </div>
+    </div>
+  );
+}

packages/react/src/scroll-area/root/ScrollAreaRoot.tsx

@@ -75,6 +75,7 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
   const startScrollLeftRef = React.useRef(0);
   const currentOrientationRef = React.useRef<'vertical' | 'horizontal'>('vertical');
   const scrollPositionRef = React.useRef(DEFAULT_COORDS);
+  const savedSnapTypeRef = React.useRef<string | null>(null);
 
   function startScrolling(vertical: boolean) {
     const setScrolling = vertical ? setScrollingY : setScrollingX;
@@ -101,6 +102,20 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
     }
   });
 
+  // CSS scroll snap forces every programmatic scroll to land on a snap
+  // point, making thumb dragging jump between snap points. Native
+  // scrollbars suppress snapping while dragging, so disable it until the
+  // pointer is released; restoring the value re-snaps the viewport. The
+  // save is guarded so a second pointer during an active drag can't
+  // clobber the saved value with `none`.
+  const disableViewportSnap = useStableCallback(() => {
+    const viewportEl = viewportRef.current;
+    if (viewportEl && savedSnapTypeRef.current === null) {
+      savedSnapTypeRef.current = viewportEl.style.scrollSnapType;
+      viewportEl.style.scrollSnapType = 'none';
+    }
+  });
+
   const handlePointerDown = useStableCallback((event: React.PointerEvent) => {
     if (event.button !== 0) {
       return;
@@ -116,9 +131,11 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
       | 'vertical'
       | 'horizontal';
 
-    if (viewportRef.current) {
-      startScrollTopRef.current = viewportRef.current.scrollTop;
-      startScrollLeftRef.current = viewportRef.current.scrollLeft;
+    const viewportEl = viewportRef.current;
+    if (viewportEl) {
+      startScrollTopRef.current = viewportEl.scrollTop;
+      startScrollLeftRef.current = viewportEl.scrollLeft;
+      disableViewportSnap();
     }
 
     const thumb =
@@ -173,6 +190,13 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
   const handlePointerUp = useStableCallback((event: React.PointerEvent) => {
     thumbDraggingRef.current = false;
 
+    if (savedSnapTypeRef.current !== null) {
+      if (viewportRef.current) {
+        viewportRef.current.style.scrollSnapType = savedSnapTypeRef.current;
+      }
+      savedSnapTypeRef.current = null;
+    }
+
     const thumb =
       currentOrientationRef.current === 'vertical' ? thumbYRef.current : thumbXRef.current;
     // `pointercancel` releases capture implicitly, so guard against releasing a
@@ -237,6 +261,7 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
       handlePointerMove,
       handlePointerUp,
       handleScroll,
+      disableViewportSnap,
       cornerSize,
       setCornerSize,
       thumbSize,
@@ -269,6 +294,7 @@ export const ScrollAreaRoot = React.forwardRef(function ScrollAreaRoot(
       handlePointerMove,
       handlePointerUp,
       handleScroll,
+      disableViewportSnap,
       cornerSize,
       thumbSize,
       hasMeasuredScrollbar,

packages/react/src/scroll-area/root/ScrollAreaRootContext.ts

@@ -32,6 +32,7 @@ export interface ScrollAreaRootContext {
   handlePointerMove: (event: React.PointerEvent) => void;
   handlePointerUp: (event: React.PointerEvent) => void;
   handleScroll: (scrollPosition: Coords) => void;
+  disableViewportSnap: () => void;
   rootId: string | undefined;
   hiddenState: HiddenState;
   setHiddenState: React.Dispatch<React.SetStateAction<HiddenState>>;

packages/react/src/scroll-area/scrollbar/ScrollAreaScrollbar.test.tsx

@@ -397,6 +397,61 @@ describe('<ScrollArea.Scrollbar />', () => {
     });
   });
 
+  // The jump-to-click assignment must run with snapping already disabled, or the
+  // assigned position quantizes to the nearest snap point and the thumb stays
+  // offset from the pointer for the whole drag. Requires real layout for the
+  // track/thumb offset math, so Chromium only.
+  describe.skipIf(isJSDOM)('scroll snap on track press', () => {
+    it('does not snap the initial jump-to-click position', async () => {
+      await render(
+        <ScrollArea.Root style={{ width: 400, height: 200 }}>
+          <ScrollArea.Viewport
+            data-testid="viewport"
+            style={{ width: '100%', height: '100%', scrollSnapType: 'x mandatory' }}
+          >
+            <div style={{ display: 'flex' }}>
+              {Array.from({ length: 10 }, (_, index) => (
+                <div
+                  key={index}
+                  style={{ flexShrink: 0, width: 200, height: 100, scrollSnapAlign: 'start' }}
+                />
+              ))}
+            </div>
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar orientation="horizontal" data-testid="scrollbar" keepMounted>
+            <ScrollArea.Thumb data-testid="thumb" />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>,
+      );
+
+      const viewport = screen.getByTestId('viewport') as HTMLDivElement;
+      const scrollbar = screen.getByTestId('scrollbar');
+      const thumb = screen.getByTestId('thumb');
+      await waitFor(() => expect(thumb.offsetWidth).toBeGreaterThan(0));
+
+      // Aim mid-way between the 800 and 1000 snap points (200px items).
+      const targetScroll = 900;
+      const maxScroll = viewport.scrollWidth - viewport.clientWidth;
+      const maxThumbOffset = scrollbar.offsetWidth - thumb.offsetWidth;
+      const rect = scrollbar.getBoundingClientRect();
+      const clickX =
+        rect.left + (targetScroll / maxScroll) * maxThumbOffset + thumb.offsetWidth / 2;
+
+      fireEvent.pointerDown(scrollbar, {
+        button: 0,
+        clientX: clickX,
+        clientY: rect.top + rect.height / 2,
+        pointerId: 1,
+      });
+
+      expect(Math.abs(viewport.scrollLeft - targetScroll)).toBeLessThanOrEqual(1);
+
+      // Releasing restores snapping, which re-snaps to the nearest snap point.
+      fireEvent.pointerUp(scrollbar, { pointerId: 1 });
+      await waitFor(() => expect(viewport.scrollLeft % 200).toBe(0));
+    });
+  });
+
   // A short or heavily padded track drives `maxThumbOffset` to zero or negative
   // once the thumb hits its `MIN_THUMB_SIZE` floor. Dragging the thumb then
   // divides by a non-positive offset, teleporting the scroll position to an

packages/react/src/scroll-area/scrollbar/ScrollAreaScrollbar.tsx

@@ -43,6 +43,7 @@ export const ScrollAreaScrollbar = React.forwardRef(function ScrollAreaScrollbar
     handlePointerDown,
     handlePointerUp,
     handleScroll,
+    disableViewportSnap,
     rootId,
     thumbSize,
     hasMeasuredScrollbar,
@@ -162,6 +163,12 @@ export const ScrollAreaScrollbar = React.forwardRef(function ScrollAreaScrollbar
         const scrollRatio = clickPosition / maxThumbOffset;
         const maxScrollDistance = scrollableSize - viewportSize;
 
+        // Disable snapping before the jump-to-click assignment, or the
+        // assigned position quantizes to the nearest snap point and the thumb
+        // stays offset from the pointer for the whole drag. `handlePointerDown`
+        // below re-runs this as a guarded no-op for the thumb-drag path.
+        disableViewportSnap();
+
         if (vertical) {
           viewportEl.scrollTop = scrollRatio * maxScrollDistance;
         } else if (direction === 'rtl') {

packages/react/src/scroll-area/thumb/ScrollAreaThumb.test.tsx

@@ -239,6 +239,80 @@ describe('<ScrollArea.Thumb />', () => {
     await waitFor(() => expect(scrollbar).not.toHaveAttribute('data-scrolling'));
   });
 
+  describe('scroll snap', () => {
+    function defineThumbPointerCapture(thumb: HTMLElement) {
+      Object.defineProperties(thumb, {
+        setPointerCapture: {
+          configurable: true,
+          value: () => {},
+        },
+        hasPointerCapture: {
+          configurable: true,
+          value: () => false,
+        },
+      });
+    }
+
+    function renderWithSnap() {
+      return render(
+        <ScrollArea.Root style={{ width: 200, height: 200 }}>
+          <ScrollArea.Viewport
+            data-testid="viewport"
+            style={{ width: '100%', height: '100%', scrollSnapType: 'y mandatory' }}
+          >
+            <div style={{ width: 200, height: 1000 }} />
+          </ScrollArea.Viewport>
+          <ScrollArea.Scrollbar orientation="vertical" keepMounted>
+            <ScrollArea.Thumb data-testid="thumb" />
+          </ScrollArea.Scrollbar>
+        </ScrollArea.Root>,
+      );
+    }
+
+    it('disables viewport scroll snap while dragging and restores it on release', async () => {
+      await renderWithSnap();
+
+      const viewport = screen.getByTestId('viewport');
+      const thumb = screen.getByTestId('thumb');
+      defineThumbPointerCapture(thumb);
+
+      fireEvent.pointerDown(thumb, { button: 0, clientY: 0, pointerId: 1 });
+      expect(viewport.style.scrollSnapType).toBe('none');
+
+      fireEvent.pointerUp(thumb, { pointerId: 1 });
+      expect(viewport.style.scrollSnapType).toBe('y mandatory');
+    });
+
+    it('restores viewport scroll snap on pointer cancel', async () => {
+      await renderWithSnap();
+
+      const viewport = screen.getByTestId('viewport');
+      const thumb = screen.getByTestId('thumb');
+      defineThumbPointerCapture(thumb);
+
+      fireEvent.pointerDown(thumb, { button: 0, clientY: 0, pointerId: 1 });
+      expect(viewport.style.scrollSnapType).toBe('none');
+
+      fireEvent.pointerCancel(thumb, { pointerId: 1 });
+      expect(viewport.style.scrollSnapType).toBe('y mandatory');
+    });
+
+    it('keeps the saved scroll snap value when a second pointer starts mid-drag', async () => {
+      await renderWithSnap();
+
+      const viewport = screen.getByTestId('viewport');
+      const thumb = screen.getByTestId('thumb');
+      defineThumbPointerCapture(thumb);
+
+      fireEvent.pointerDown(thumb, { button: 0, clientY: 0, pointerId: 1 });
+      fireEvent.pointerDown(thumb, { button: 0, clientY: 0, pointerId: 2 });
+      expect(viewport.style.scrollSnapType).toBe('none');
+
+      fireEvent.pointerUp(thumb, { pointerId: 1 });
+      expect(viewport.style.scrollSnapType).toBe('y mandatory');
+    });
+  });
+
   describe('data-scrolling attribute', () => {
     const { render: renderWithClock, clock } = createRenderer();