Theme

npm_versionnpm Paragon package page

A headless React hook that may be used as the foundation for building carousel-like UI components.

Sample Usage

The following example demonstrates how to use useOverflowScroll to build a carousel-like UI component.

Any Paragon component or export may be added to the code example.

The hook accepts the following options:

  • childQuerySelector. A CSS query selector that can be used to find the child elements within the overflow container.
  • onScrollPrevious. Supports a callback function when user scrolls to the previous element via a control.
  • onScrollNext. Supports a callback function when user scrolls to the next element via a control.
  • hasInteractiveChildren. Whether the child elements are interactive (e.g., clickable cards).
  • disableScroll. An optional flag to disable the scroll behavior for the overflow container.
  • disableOpacityMasks. An optional flag to disable the opacity masks at the start/end of the overflow container (if applicable).
  • scrollAnimationBehavior. Allows overriding the default scroll behavior (e.g., "smooth", "instant", "auto").

The hook returns the following:

  • Refs
    • overflowRef. The ref to pass to your overflow container. Note that this element may receive style overrides for position: relative; and overflow-x: scroll (optionally).
  • Behaviors
    • scrollToPrevious. A click handler to scroll the overflow container to the previous element.
    • scrollToNext. A click handler to scroll the overflow container to the next element.
  • Scroll state
    • isScrolledToStart. Whether the overflow container is scrolled to the start.
    • isScrolledToEnd. Whether the overflow container is scrolled to the end.
    • activeChildElementIndex. The index of the child element that is currently deemed to be "active", i.e. the child element used as the reference position for any scrollToPrevious or scrollToNext calls.

See OverflowScroll for React components that encapsulate the logic within useOverflowScroll.

Use of offset and offsetType

Any Paragon component or export may be added to the code example.