React Scrollable Hook

A React hook for managing scrollable containers with TypeScript support, providing scroll position tracking and automatic scroll-to-bottom functionality.

Installation

npm install @lonestone/usescrollable
# or
yarn add @lonestone/usescrollable
# or
pnpm add @lonestone/usescrollable

Features

• 📜 Track scroll position (top, middle, bottom)
• 🔄 Automatic scroll-to-bottom functionality
• 📏 Detect if content is scrollable
• ⚡️ Optimized performance with ResizeObserver
• 🛡️ Type-safe with TypeScript
• 🧪 Well tested
• 💬 Perfect for chat applications and infinite scrolling lists

Usage

import { useScrollable } from '@lonestone/usescrollable'
import { useEffect } from 'react'

function ChatContainer() {
  const {
    containerRef,
    contentRef,
    isScrollable,
    scrollPosition,
    scrollToBottom,
    handleScroll,
  } = useScrollable()

  // Basic usage
  return (
    <div
      ref={containerRef}
      onScroll={handleScroll}
      style={{ height: '400px', overflow: 'auto' }}
    >
      <div ref={contentRef}>
        {/* Your scrollable content here */}
        {messages.map((message) => (
          <div key={message.id}>{message.text}</div>
        ))}
      </div>
    </div>
  )
}

function AutoScrollChat() {
  const {
    containerRef,
    contentRef,
    scrollPosition,
    scrollToBottom,
    handleScroll,
  } = useScrollable()

  // Automatically scroll to bottom when new messages arrive
  useEffect(() => {
    scrollToBottom()
  }, [messages.length])

  return (
    <div
      ref={containerRef}
      onScroll={handleScroll}
      style={{ height: '400px', overflow: 'auto' }}
    >
      <div ref={contentRef}>
        {messages.map((message) => (
          <div key={message.id}>{message.text}</div>
        ))}
      </div>
    </div>
  )
}

API Reference

function useScrollable(): {
  containerRef: RefObject<HTMLDivElement>
  contentRef: RefObject<HTMLDivElement>
  isScrollable: boolean
  scrollPosition: ScrollPosition
  scrollToBottom: () => void
  handleScroll: React.UIEventHandler<HTMLDivElement>
}

enum ScrollPosition {
  None, // Not enough content to scroll
  Top, // Scrolled to top
  Bottom, // Scrolled to bottom
  Middle, // Somewhere in between
}

Returns

| Property | Type | Description | | -------------- | ------------------------------------ | ---------------------------------------------------- | | containerRef | RefObject | Ref for the scrollable container element | | contentRef | RefObject | Ref for the content inside the scrollable container | | isScrollable | boolean | Whether the content is large enough to be scrollable | | scrollPosition | ScrollPosition | Current scroll position state | | scrollToBottom | () => void | Function to smoothly scroll to the bottom | | handleScroll | React.UIEventHandler | Event handler for scroll events |

Features in Detail

Scroll Position Tracking

The hook automatically tracks the scroll position:

function ScrollTracker() {
  const { containerRef, contentRef, scrollPosition, handleScroll } =
    useScrollable()

  return (
    <div>
      <div>Current position: {ScrollPosition[scrollPosition]}</div>
      <div
        ref={containerRef}
        onScroll={handleScroll}
        style={{ height: '400px', overflow: 'auto' }}
      >
        <div ref={contentRef}>{/* Your content here */}</div>
      </div>
    </div>
  )
}

Automatic Scroll-to-Bottom

Perfect for chat applications or dynamic content:

function AutoScrollContent() {
  const { containerRef, contentRef, scrollToBottom, handleScroll } =
    useScrollable()

  useEffect(() => {
    // Call scrollToBottom whenever new content is added
    scrollToBottom()
  }, [contentLength])

  return (
    <div
      ref={containerRef}
      onScroll={handleScroll}
      style={{ height: '400px', overflow: 'auto' }}
    >
      <div ref={contentRef}>{/* Dynamic content here */}</div>
    </div>
  )
}

Best Practices

• Always attach both containerRef and contentRef to their respective elements
• Use the handleScroll event handler to track scroll position
• Consider performance when adding or removing content frequently
• Use isScrollable to conditionally render scroll-related UI elements
• Call scrollToBottom after content updates when needed

License

This project is licensed under the Unlicense.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.