use-stick-to-bottom

The <StickToBottom> component acts as a provider that manages scroll stickiness logic. It can be used in two ways:

1. Render Prop Pattern: Pass a function as children to access the StickToBottomContext directly.
2. Component Pattern: Use the <StickToBottom.Content> sub-component inside <StickToBottom> to automatically wire up the necessary scroll and content refs.

Configuration Options

import { StickToBottom } from 'use-stick-to-bottom';

function MyComponent() {
  return (
    <StickToBottom resize damping={20}>
      <StickToBottom.Content>
        {({ scrollToBottom, isAtBottom }) => (
          <div>
            <button onClick={scrollToBottom}>Scroll to bottom</button>
            <p>Is at bottom: {isAtBottom ? 'Yes' : 'No'}</p>
            <div style={{ height: '1000px' }}>Long Content</div>
          </div>
        )}
      </StickToBottom.Content>
    </StickToBottom>
  );
}

The <StickToBottom> component is the easiest way to implement stick-to-bottom behavior. It manages refs for you and provides a context that child components can consume to check if the user is at the bottom or to trigger a scroll.

Key props:

• resize: Controls how the component handles content resizing (e.g., "smooth").
• initial: Controls the initial scroll behavior (e.g., "smooth").

Sub-components:

• <StickToBottom.Content>: Wraps the content that should be tracked for resizing and scrolling.

import { StickToBottom, useStickToBottomContext } from 'use-stick-to-bottom';

function Chat() {
  return (
    <StickToBottom className="h-[50vh] relative" resize="smooth" initial="smooth">
      <StickToBottom.Content className="flex flex-col gap-4">
        {messages.map((message) => (
          <Message key={message.id} message={message} />
        ))}
      </StickToBottom.Content>

      <ScrollToBottom />

      {/* This component uses `useStickToBottomContext` to scroll to bottom when the user enters a message */}
      <ChatBox />
    </StickToBottom>
  );
}

function ScrollToBottom() {
  const { isAtBottom, scrollToBottom } = useStickToBottomContext();

  return (
    !isAtBottom && (
      <button
        className="absolute i-ph-arrow-circle-down-fill text-4xl rounded-lg left-[50%] translate-x-[-50%] bottom-0"
        onClick={() => scrollToBottom()}
      />
    )
  );
}

When initializing useStickToBottom, you can pass a StickToBottomOptions object to customize behavior.

Options

• resize: An Animation type defining how the container scrolls when the content size changes.
• initial: An Animation or boolean defining the initial scroll behavior when the component mounts.
• targetScrollTop: A function (targetScrollTop: number, context: ScrollElements) => number that allows you to override the calculated target scroll position.

Spring Animation Configuration

If you use a spring animation instead of 'instant', you can tune the following:

• damping: (0 to 1) How much to damp the animation. 0 is no damping, 1 is full damping. Default: 0.7.
• stiffness: How fast/slow the animation gets up to speed. Default: 0.05.
• mass: The inertial mass. Higher numbers make the animation slower. Default: 1.25.

const { scrollRef, contentRef } = useStickToBottom({
  resize: {
    damping: 0.8,
    stiffness: 0.1,
    mass: 1.0
  },
  initial: 'instant'
});

The useStickToBottom hook provides programmatic control over a scrollable container to keep it stuck to the bottom (e.g., for chat windows). It returns refs to attach to the scroll container and the content element, along with methods to trigger scrolling and state information.

To use it, you must provide two refs:

1. scrollRef: Attach this to the element that has the overflow/scroll property.
2. contentRef: Attach this to the element containing the actual content that changes size.

Basic Usage

import { useStickToBottom } from 'use-stick-to-bottom';

function ChatWindow() {
  const {
    scrollRef, 
    contentRef, 
    scrollToBottom, 
    isAtBottom 
  } = useStickToBottom();

  const handleNewMessage = async () => {
    // ... add message to state
    await scrollToBottom();
  };

  return (
    <div ref={scrollRef} style={{ overflowY: 'auto', height: '400px' }}>
      <div ref={contentRef}>
        {/* Messages go here */}
      </div>
    </div>
  );
}