[slider] Add thumbCollisionBehavior prop (#2856)

Author: atomiks

docs/reference/generated/slider-root.json

@@ -42,6 +42,12 @@
       "description": "How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:\n- `center`: The center of the thumb is aligned with the control edge\n- `edge`: The thumb is inset within the control such that its edge is aligned with the control edge\n- `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return",
       "detailedType": "'center' | 'edge' | 'edge-client-only' | undefined"
     },
+    "thumbCollisionBehavior": {
+      "type": "'none' | 'push' | 'swap'",
+      "default": "'push'",
+      "description": "Controls how thumbs behave when they collide during pointer interactions.\n\n- `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.\n- `'swap'`: Thumbs swap places when dragged past each other.\n- `'none'`: Thumbs cannot move past each other; excess movement is ignored.",
+      "detailedType": "'none' | 'push' | 'swap' | undefined"
+    },
     "step": {
       "type": "number",
       "default": "1",

docs/src/app/(public)/(content)/react/components/slider/page.mdx

@@ -41,6 +41,8 @@ To create a range slider:
 1. Pass an array of values and place a `<Slider.Thumb>` for each value in the array
 2. Additionally for server-side rendering, specify a numeric `index` for each thumb that corresponds to the index of its value in the value array
 
+Thumbs can be configured to behave differently when they collide during pointer interactions using the `thumbCollisionBehavior` prop on `<Slider.Root>`.
+
 import { DemoSliderRangeSlider } from './demos/range-slider';
 
 <DemoSliderRangeSlider compact />

packages/react/src/slider/control/SliderControl.tsx

@@ -4,6 +4,7 @@ import { isElement } from '@floating-ui/utils/dom';
 import { ownerDocument } from '@base-ui-components/utils/owner';
 import { useAnimationFrame } from '@base-ui-components/utils/useAnimationFrame';
 import { useStableCallback } from '@base-ui-components/utils/useStableCallback';
+import { useValueAsRef } from '@base-ui-components/utils/useValueAsRef';
 import { activeElement, contains } from '../../floating-ui-react/utils';
 import type { Coords } from '../../floating-ui-react/types';
 import { clamp } from '../../utils/clamp';
@@ -19,9 +20,9 @@ import { useSliderRootContext } from '../root/SliderRootContext';
 import { sliderStateAttributesMapping } from '../root/stateAttributesMapping';
 import type { SliderRoot } from '../root/SliderRoot';
 import { getMidpoint } from '../utils/getMidpoint';
-import { replaceArrayItemAtIndex } from '../utils/replaceArrayItemAtIndex';
 import { roundValueToStep } from '../utils/roundValueToStep';
 import { validateMinimumDistance } from '../utils/validateMinimumDistance';
+import { resolveThumbCollision } from '../utils/resolveThumbCollision';
 
 const INTENTIONAL_DRAG_COUNT_THRESHOLD = 2;
 
@@ -101,13 +102,15 @@ export const SliderControl = React.forwardRef(function SliderControl(
     pressedInputRef,
     pressedThumbCenterOffsetRef,
     pressedThumbIndexRef,
+    pressedValuesRef,
     registerFieldControlRef,
     renderBeforeHydration,
     setActive,
     setDragging,
     setValue,
     state,
     step,
+    thumbCollisionBehavior,
     thumbRefs,
     values,
   } = useSliderRootContext();
@@ -133,6 +136,23 @@ export const SliderControl = React.forwardRef(function SliderControl(
   // The offset amount to each side of the control for inset sliders.
   // This value should be equal to the radius or half the width/height of the thumb.
   const insetThumbOffsetRef = React.useRef(0);
+  const latestValuesRef = useValueAsRef(values);
+
+  const updatePressedThumb = useStableCallback((nextIndex: number) => {
+    if (pressedThumbIndexRef.current !== nextIndex) {
+      pressedThumbIndexRef.current = nextIndex;
+    }
+
+    const thumbElement = thumbRefs.current[nextIndex];
+
+    if (!thumbElement) {
+      pressedThumbCenterOffsetRef.current = null;
+      pressedInputRef.current = null;
+      return;
+    }
+
+    pressedInputRef.current = thumbElement.querySelector<HTMLInputElement>('input[type="range"]');
+  });
 
   const getFingerState = useStableCallback((fingerCoords: Coords): FingerState | null => {
     const control = controlRef.current;
@@ -165,25 +185,42 @@ export const SliderControl = React.forwardRef(function SliderControl(
       return {
         value: newValue,
         thumbIndex: 0,
+        didSwap: false,
       };
     }
 
-    const minValueDifference = minStepsBetweenValues * step;
+    const thumbIndex = pressedThumbIndexRef.current;
+
+    if (thumbIndex < 0) {
+      return null;
+    }
+
+    const collisionResult = resolveThumbCollision({
+      behavior: thumbCollisionBehavior,
+      values,
+      currentValues: latestValuesRef.current ?? values,
+      initialValues: pressedValuesRef.current,
+      pressedIndex: thumbIndex,
+      nextValue: newValue,
+      min,
+      max,
+      step,
+      minStepsBetweenValues,
+    });
 
-    // Bound the new value to the thumb's neighbours.
-    newValue = clamp(
-      newValue,
-      values[pressedThumbIndexRef.current - 1] + minValueDifference || -Infinity,
-      values[pressedThumbIndexRef.current + 1] - minValueDifference || Infinity,
-    );
+    if (thumbCollisionBehavior === 'swap' && collisionResult.didSwap) {
+      updatePressedThumb(collisionResult.thumbIndex);
+    } else {
+      pressedThumbIndexRef.current = collisionResult.thumbIndex;
+    }
 
-    return {
-      value: replaceArrayItemAtIndex(values, pressedThumbIndexRef.current, newValue),
-      thumbIndex: pressedThumbIndexRef.current,
-    };
+    return collisionResult;
   });
 
   const startPressing = useStableCallback((fingerCoords: Coords) => {
+    pressedValuesRef.current = range ? values.slice() : null;
+    latestValuesRef.current = values;
+
     const pressedThumbIndex = pressedThumbIndexRef.current;
     let closestThumbIndex = pressedThumbIndex;
 
@@ -219,7 +256,7 @@ export const SliderControl = React.forwardRef(function SliderControl(
     }
 
     if (closestThumbIndex > -1 && closestThumbIndex !== pressedThumbIndex) {
-      pressedThumbIndexRef.current = closestThumbIndex;
+      updatePressedThumb(closestThumbIndex);
     }
 
     if (inset) {
@@ -270,6 +307,12 @@ export const SliderControl = React.forwardRef(function SliderControl(
           activeThumbIndex: finger.thumbIndex,
         }),
       );
+
+      latestValuesRef.current = Array.isArray(finger.value) ? finger.value : [finger.value];
+
+      if (finger.didSwap) {
+        focusThumb(finger.thumbIndex);
+      }
     }
   });
 
@@ -282,25 +325,17 @@ export const SliderControl = React.forwardRef(function SliderControl(
     pressedThumbIndexRef.current = -1;
 
     const fingerCoords = getFingerCoords(nativeEvent, touchIdRef);
-
-    if (fingerCoords == null) {
-      return;
-    }
-
-    const finger = getFingerState(fingerCoords);
-
-    if (finger == null) {
-      return;
+    const finger = fingerCoords != null ? getFingerState(fingerCoords) : null;
+
+    if (finger != null) {
+      const commitReason = lastChangeReasonRef.current;
+      validation.commit(lastChangedValueRef.current ?? finger.value);
+      onValueCommitted(
+        lastChangedValueRef.current ?? finger.value,
+        createGenericEventDetails(commitReason, nativeEvent),
+      );
     }
 
-    const commitReason = lastChangeReasonRef.current;
-
-    validation.commit(lastChangedValueRef.current ?? finger.value);
-    onValueCommitted(
-      lastChangedValueRef.current ?? finger.value,
-      createGenericEventDetails(commitReason, nativeEvent),
-    );
-
     if (
       'pointerType' in nativeEvent &&
       controlRef.current?.hasPointerCapture(nativeEvent.pointerId)
@@ -309,6 +344,7 @@ export const SliderControl = React.forwardRef(function SliderControl(
     }
 
     touchIdRef.current = null;
+    pressedValuesRef.current = null;
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
     stopListening();
   }
@@ -342,6 +378,12 @@ export const SliderControl = React.forwardRef(function SliderControl(
           activeThumbIndex: finger.thumbIndex,
         }),
       );
+
+      latestValuesRef.current = Array.isArray(finger.value) ? finger.value : [finger.value];
+
+      if (finger.didSwap) {
+        focusThumb(finger.thumbIndex);
+      }
     }
 
     moveCountRef.current = 0;
@@ -356,6 +398,7 @@ export const SliderControl = React.forwardRef(function SliderControl(
     doc.removeEventListener('pointerup', handleTouchEnd);
     doc.removeEventListener('touchmove', handleTouchMove);
     doc.removeEventListener('touchend', handleTouchEnd);
+    pressedValuesRef.current = null;
   });
 
   const focusFrame = useAnimationFrame();
@@ -438,6 +481,12 @@ export const SliderControl = React.forwardRef(function SliderControl(
                   activeThumbIndex: finger.thumbIndex,
                 }),
               );
+
+              latestValuesRef.current = Array.isArray(finger.value) ? finger.value : [finger.value];
+
+              if (finger.didSwap) {
+                focusThumb(finger.thumbIndex);
+              }
             }
           }
 
@@ -463,10 +512,12 @@ export const SliderControl = React.forwardRef(function SliderControl(
 interface FingerState {
   value: number | number[];
   thumbIndex: number;
+  didSwap: boolean;
 }
 
 export interface SliderControlProps extends BaseUIComponentProps<'div', SliderRoot.State> {}
 
 export namespace SliderControl {
+  export type State = SliderRoot.State;
   export type Props = SliderControlProps;
 }

packages/react/src/slider/root/SliderRoot.tsx

@@ -79,6 +79,7 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
     onValueCommitted: onValueCommittedProp,
     orientation = 'horizontal',
     step = 1,
+    thumbCollisionBehavior = 'push',
     thumbAlignment = 'center',
     value: valueProp,
     ...elementProps
@@ -134,6 +135,8 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
   // This is updated on pointerdown, which is sooner than the `active/activeIndex`
   // state which is updated later when the nested `input` receives focus.
   const pressedThumbIndexRef = React.useRef(-1);
+  // The values when the current drag interaction started.
+  const pressedValuesRef = React.useRef<readonly number[] | null>(null);
   const lastChangedValueRef = React.useRef<number | readonly number[] | null>(null);
   const lastChangeReasonRef = React.useRef<SliderRoot.ChangeEventReason>('none');
 
@@ -142,17 +145,25 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
   // We can't use the :active browser pseudo-classes.
   // - The active state isn't triggered when clicking on the rail.
   // - The active state isn't transferred when inversing a range slider.
-  const [active, setActive] = React.useState(-1);
+  const [active, setActiveState] = React.useState(-1);
+  const [lastUsedThumbIndex, setLastUsedThumbIndex] = React.useState(-1);
   const [dragging, setDragging] = React.useState(false);
   const [thumbMap, setThumbMap] = React.useState(
     () => new Map<Node, CompositeMetadata<ThumbMetadata> | null>(),
   );
-
   const [indicatorPosition, setIndicatorPosition] = React.useState<(number | undefined)[]>([
     undefined,
     undefined,
   ]);
 
+  const setActive = useStableCallback((value: number) => {
+    setActiveState(value);
+
+    if (value !== -1) {
+      setLastUsedThumbIndex(value);
+    }
+  });
+
   useField({
     id,
     commit: validation.commit,
@@ -314,6 +325,7 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
       inset: thumbAlignment !== 'center',
       labelId: ariaLabelledby,
       largeStep,
+      lastUsedThumbIndex,
       lastChangedValueRef,
       lastChangeReasonRef,
       locale,
@@ -326,6 +338,7 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
       pressedInputRef,
       pressedThumbCenterOffsetRef,
       pressedThumbIndexRef,
+      pressedValuesRef,
       registerFieldControlRef,
       renderBeforeHydration: thumbAlignment === 'edge',
       setActive,
@@ -334,6 +347,7 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
       setValue,
       state,
       step,
+      thumbCollisionBehavior,
       thumbMap,
       thumbRefs,
       values,
@@ -349,6 +363,7 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
       handleInputChange,
       indicatorPosition,
       largeStep,
+      lastUsedThumbIndex,
       lastChangedValueRef,
       lastChangeReasonRef,
       locale,
@@ -361,13 +376,15 @@ export const SliderRoot = React.forwardRef(function SliderRoot<
       pressedInputRef,
       pressedThumbCenterOffsetRef,
       pressedThumbIndexRef,
+      pressedValuesRef,
       registerFieldControlRef,
       setActive,
       setDragging,
       setIndicatorPosition,
       setValue,
       state,
       step,
+      thumbCollisionBehavior,
       thumbAlignment,
       thumbMap,
       thumbRefs,
@@ -440,6 +457,7 @@ export interface SliderRootState extends FieldRoot.State {
    */
   values: readonly number[];
 }
+
 export interface SliderRootProps<
   Value extends number | readonly number[] = number | readonly number[],
 > extends BaseUIComponentProps<'div', SliderRoot.State> {
@@ -509,6 +527,16 @@ export interface SliderRootProps<
    * @default 'center'
    */
   thumbAlignment?: 'center' | 'edge' | 'edge-client-only';
+  /**
+   * Controls how thumbs behave when they collide during pointer interactions.
+   *
+   * - `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.
+   * - `'swap'`: Thumbs swap places when dragged past each other.
+   * - `'none'`: Thumbs cannot move past each other; excess movement is ignored.
+   *
+   * @default 'push'
+   */
+  thumbCollisionBehavior?: 'push' | 'swap' | 'none';
   /**
    * The value of the slider.
    * For ranged sliders, provide an array with two values.

packages/react/src/slider/root/SliderRootContext.ts

@@ -11,6 +11,10 @@ export interface SliderRootContext {
    * The index of the active thumb.
    */
   active: number;
+  /**
+   * The index of the most recently interacted thumb.
+   */
+  lastUsedThumbIndex: number;
   controlRef: React.RefObject<HTMLElement | null>;
   dragging: boolean;
   disabled: boolean;
@@ -65,9 +69,10 @@ export interface SliderRootContext {
   pressedInputRef: React.RefObject<HTMLInputElement | null>;
   pressedThumbCenterOffsetRef: React.RefObject<number | null>;
   pressedThumbIndexRef: React.RefObject<number>;
-  registerFieldControlRef: React.RefCallback<Element> | null;
+  pressedValuesRef: React.RefObject<readonly number[] | null>;
   renderBeforeHydration: boolean;
-  setActive: React.Dispatch<React.SetStateAction<number>>;
+  registerFieldControlRef: React.RefCallback<Element> | null;
+  setActive: (index: number) => void;
   setDragging: React.Dispatch<React.SetStateAction<boolean>>;
   setIndicatorPosition: React.Dispatch<React.SetStateAction<(number | undefined)[]>>;
   /**
@@ -81,6 +86,7 @@ export interface SliderRootContext {
    * @default 1
    */
   step: number;
+  thumbCollisionBehavior: 'push' | 'swap' | 'none';
   thumbMap: Map<Node, CompositeMetadata<ThumbMetadata> | null>;
   thumbRefs: React.RefObject<(HTMLElement | null)[]>;
   /**