Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zayne-labs/ui/llms.txt

Use this file to discover all available pages before exploring further.

A headless hook for implementing drag-to-scroll functionality with scroll buttons.

​
Import

import { useDragScroll } from "@zayne-labs/ui-react/ui/drag-scroll";

​
Usage

function MyComponent() {
  const { propGetters } = useDragScroll<HTMLDivElement>({
    orientation: "horizontal",
    scrollAmount: "item",
  });

  return (
    <div>
      <button {...propGetters.getBackButtonProps()}>←</button>
      <div {...propGetters.getRootProps()}>
        <div {...propGetters.getItemProps()}>Item 1</div>
        <div {...propGetters.getItemProps()}>Item 2</div>
        <div {...propGetters.getItemProps()}>Item 3</div>
      </div>
      <button {...propGetters.getNextButtonProps()}>→</button>
    </div>
  );
}

​
Hook Options

​
orientation
'horizontal' | 'vertical' | 'both'
default:"horizontal"
The direction in which scrolling is allowed
  • horizontal - Only scroll horizontally
  • vertical - Only scroll vertically
  • both - Scroll in both directions
​
scrollAmount
'item' | number
default:"item"
Amount to scroll when using navigation buttons
  • "item" - Scroll by the width/height of the first child element
  • number - Scroll by a fixed pixel amount
​
usage
'allScreens' | 'desktopOnly' | 'mobileAndTabletOnly'
default:"allScreens"
Device usage constraints for drag behavior
  • allScreens - Drag works on all devices
  • desktopOnly - Drag works only on desktop (width >= 768px)
  • mobileAndTabletOnly - Drag works only on mobile/tablet (width < 768px)
​
classNames
object
Custom class names for drag scroll parts
  • base?: string - Root container classes
  • item?: string - Item classes
​
disableInternalStateSubscription
boolean
default:false
Whether to disable the internal state subscription for setting data attributesThis is useful if you want to subscribe to the state yourself

​
Return Value

​
propGetters

Object containing prop getter functions for each component part.
​
propGetters.getRootProps
function
Returns props for the scrollable container element
(props?: PartProps["root"]["input"]) => PartProps["root"]["output"]
Returns:
  • Element props with scroll behavior classes
  • ref callback for container registration
  • Data attributes: data-scope="drag-scroll", data-part="root", data-dragging (when dragging)
​
propGetters.getItemProps
function
Returns props for individual scroll items
(props?: PartProps["item"]["input"]) => PartProps["item"]["output"]
Returns:
  • Element props with snap-center classes
  • Data attributes: data-scope="drag-scroll", data-part="item"
​
propGetters.getBackButtonProps
function
Returns props for the previous/back scroll button
(props?: PartProps["backButton"]["input"]) => PartProps["backButton"]["output"]
Returns:
  • Button props with click handler to scroll backward
  • disabled when at the start of scroll
  • Data attributes: data-scope="drag-scroll", data-part="back-button", data-disabled
​
propGetters.getNextButtonProps
function
Returns props for the next/forward scroll button
(props?: PartProps["nextButton"]["input"]) => PartProps["nextButton"]["output"]
Returns:
  • Button props with click handler to scroll forward
  • disabled when at the end of scroll
  • Data attributes: data-scope="drag-scroll", data-part="next-button", data-disabled

​
containerRef

​
containerRef
React.RefObject<TElement | null>
Ref object containing the scrollable container element

​
storeApi

​
storeApi
StoreApi<DragScrollStore<TElement>>
Store API for accessing and subscribing to drag scroll state

​
useDragScrollStore

​
useDragScrollStore
function
Hook for subscribing to specific slices of the drag scroll state
const isDragging = useDragScrollStore((state) => state.isDragging);
const canGoToNext = useDragScrollStore((state) => state.canGoToNext);

​
disableInternalStateSubscription

​
disableInternalStateSubscription
boolean
The resolved value of the disableInternalStateSubscription option

​
Types

​
DragScrollStore

type DragScrollStore<TElement extends HTMLElement> = {
  // State
  canGoToNext: boolean;
  canGoToPrev: boolean;
  isDragging: boolean;
  
  // Actions
  actions: {
    cleanupDragListeners: () => void;
    goToNext: () => void;
    goToPrev: () => void;
    handleMouseDown: (event: MouseEvent) => void;
    handleMouseMove: (event: MouseEvent) => void;
    handleMouseUpOrLeave: () => void;
    handleScroll: () => void;
    initializeResizeObserver: () => (() => void) | undefined;
    setContainerRef: (element: TElement | null) => void;
    updateScrollState: () => void;
  };
};

​
DragScrollState

type DragScrollState = {
  /** Whether the container can scroll forward (right/down) */
  canGoToNext: boolean;
  /** Whether the container can scroll backward (left/up) */
  canGoToPrev: boolean;
  /** Whether the user is currently dragging */
  isDragging: boolean;
};

​
DragScrollActions

type DragScrollActions<TElement extends HTMLElement> = {
  actions: {
    cleanupDragListeners: () => void;
    goToNext: () => void;
    goToPrev: () => void;
    handleMouseDown: (event: MouseEvent) => void;
    handleMouseMove: (event: MouseEvent) => void;
    handleMouseUpOrLeave: () => void;
    handleScroll: () => void;
    initializeResizeObserver: () => (() => void) | undefined;
    setContainerRef: (element: TElement | null) => void;
    updateScrollState: () => void;
  };
};

​
UseDragScrollProps

interface UseDragScrollProps {
  orientation?: "horizontal" | "vertical" | "both";
  scrollAmount?: "item" | number;
  usage?: "allScreens" | "desktopOnly" | "mobileAndTabletOnly";
  classNames?: {
    base?: string;
    item?: string;
  };
  disableInternalStateSubscription?: boolean;
}

​
UseDragScrollResult

interface UseDragScrollResult<TElement extends HTMLElement> {
  containerRef: React.RefObject<TElement | null>;
  propGetters: DragScrollPropGetters<TElement>;
  storeApi: ReturnType<typeof createDragScrollStore<TElement>>;
  useDragScrollStore: typeof useDragScrollStoreContext;
  disableInternalStateSubscription: boolean;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us