Use Stick To Bottom

https://github.com/stackblitz-labs/use-stick-to-bottom
Admin
A zero-dependency React hook and component that automatically sticks to the bottom of a container,...
Tokens:24,560
Snippets:135
Trust Score:7.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### StickToBottom component props example

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Example of passing the same options as props to the <StickToBottom> component, including a className and initial={false} to start unpinned.

```tsx
<StickToBottom
	className="h-[50vh]"
	resize="smooth"
	initial={false}
	damping={0.5}
	stiffness={0.08}
	mass={1.5}
>
	{/* ... */}
</StickToBottom>
```

--------------------------------

### Install use-stick-to-bottom via npm

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/README.md

Install the use-stick-to-bottom package via npm. Requires no additional arguments.

```bash
npm install use-stick-to-bottom
```

--------------------------------

### useStickToBottom hook options example

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Example of configuring the useStickToBottom hook with custom spring values, a resize animation, an initial animation, and a targetScrollTop transform that clamps the target to leave a 50px margin.

```tsx
useStickToBottom({
	damping: 0.5,
	stiffness: 0.08,
	mass: 1.5,
	resize: "smooth",
	initial: { damping: 0.9, stiffness: 0.02, mass: 2 },
	targetScrollTop: (target, { scrollElement }) =>
		Math.min(target, scrollElement.scrollHeight - scrollElement.clientHeight - 50),
});
```

--------------------------------

### Custom spring config and target scroll offset

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Custom spring configuration example: sets damping, stiffness, mass, initial: "smooth", and a targetScrollTop callback that keeps a 100px footer visible. Also demonstrates isAtBottom state and scrollToBottom imperative control.

```tsx
import { useStickToBottom } from "use-stick-to-bottom";

function ChatScroll() {
  const { scrollRef, contentRef, isAtBottom, scrollToBottom } =
    useStickToBottom({
      damping: 0.5, // less damping: more bounce-back
      stiffness: 0.1, // faster to reach speed
      mass: 2, // heavier: slower animation
      initial: "smooth",
      targetScrollTop: (targetScrollTop, { scrollElement }) =>
        // never stick to the very last 100px, e.g. to keep a footer visible
        Math.max(0, targetScrollTop - 100),
    });

  if (!isAtBottom) {
    console.log("user scrolled up");
  }

  return (
    <div style={{ overflow: "auto", height: "50vh" }} ref={scrollRef}>
      <div ref={contentRef}>
        {messages.map((message) => (
          <Message key={message.id} message={message} />
        ))}
      </div>
      <button onClick={() => scrollToBottom()}>Jump to bottom</button>
    </div>
  );
}
```

--------------------------------

### Basic call to scrollToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Shows how to get scrollToBottom from the context and use it in a button onClick handler.

```tsx
const { scrollToBottom, isAtBottom } = useStickToBottomContext();

<button onClick={() => scrollToBottom()}>Back to bottom</button>
```

--------------------------------

### Custom spring options and render-prop children with StickToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

Use custom spring options (resize) and render-prop children to control stickiness. Set initial={false} to start pinned-up so the user must scroll down; the render prop exposes context.isAtBottom and context.scrollToBottom() to show a "Back to bottom" button when not at the bottom.

```tsx
import { StickToBottom } from "use-stick-to-bottom";

function Chat() {
	return (
		<StickToBottom
			className="h-[50vh]"
			resize={{ damping: 0.8, stiffness: 0.03, mass: 2 }}
			initial={false} // start pinned-up; user must scroll down
		>
			{(context) => (
				<>
					<StickToBottom.Content>
						{messages.map((message) => (
							<Message key={message.id} message={message} />
						))}
					</StickToBottom.Content>
					{!context.isAtBottom && (
						<button onClick={() => context.scrollToBottom()}>Back to bottom</button>
					)}
				</>
			)}
		</StickToBottom>
	);
}

```

```tsx
import { useRef, useEffect } from "react";
import { StickToBottom, useStickToBottom } from "use-stick-to-bottom";

function Chat() {
	const contextRef = useRef(null);
	const instance = useStickToBottom({ initial: false });

	useEffect(() => {
		// Context is usable outside render via the imperative handle
		console.log(contextRef.current?.isAtBottom);
	}, []);
}
```

--------------------------------

### Basic usage of useStickToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Basic usage example: attaches scrollRef to a scroll container and contentRef to an inner content element. The hook wires up scroll/wheel listeners and a ResizeObserver to keep the container pinned to the bottom.

```tsx
import { useStickToBottom } from "use-stick-to-bottom";

function ChatScroll() {
  const { scrollRef, contentRef } = useStickToBottom();

  return (
    <div style={{ overflow: "auto", height: "50vh" }} ref={scrollRef}>
      <div ref={contentRef}>
        {messages.map((message) => (
          <Message key={message.id} message={message} />
        ))}
      </div>
    </div>
  );
}
```

--------------------------------

### useStickToBottomContext example: AutoScrollButton component

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

Use inside a <StickToBottom> component to access whether the component is at the bottom of the scrollable area. Returns null when already at the bottom, otherwise renders a button that calls scrollToBottom().

```tsx
import { useStickToBottomContext } from "use-stick-to-bottom";

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

	if (isAtBottom) {
		return null;
	}

	return <button onClick={() => scrollToBottom()}>New messages — scroll down</button>;
}
```

--------------------------------

### `useStickToBottomContext` — missing provider

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

Documentation of the only error path in `use-stick-to-bottom`: the synchronous throw from `useStickToBottomContext` when no provider is present.

```APIDOC
## `useStickToBottomContext` — missing provider

### Description
Throws a synchronous `Error` when `useStickToBottomContext()` is called outside of a `<StickToBottom>` ancestor. This is the only error path in the library.

### Error Type
`Error` (no custom class, no error code)

### Trigger Condition
Called when no `<StickToBottom>` ancestor has provided context (context value is `null`).

### Error Message
```
use-stick-to-bottom component context must be used within a StickToBottom component
```

### Consumers Affected
Any call to `useStickToBottomContext()`, including indirect calls from `StickToBottom.Content`, when the component is not a descendant of a rendered `<StickToBottom>`.

### How to Catch
Since this is a synchronous throw during render, use a `try/catch` block inside the component:

```tsx
import { useStickToBottomContext } from "use-stick-to-bottom";

function StatusBadge() {
	let context;
	try {
		context = useStickToBottomContext();
	} catch (error) {
		// Rendered outside a <StickToBottom>: no context available.
		return <span>standalone</span>;
	}

	return <span>{context.isAtBottom ? "at bottom" : "scrolled up"}</span>;
}
```

### Source
- Thrown at `src/StickToBottom.tsx:182–184`.
- Function defined at `src/StickToBottom.tsx:179–186`.
```

--------------------------------

### StickToBottomContext

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Documentation for the `StickToBottomContext` interface, which is returned by the `useStickToBottomContext` hook.

```APIDOC
## `StickToBottomContext`

### Description
Interface representing the context object returned by `useStickToBottomContext`. It provides refs, methods, and state for controlling scroll-to-bottom behavior.

### Members
- `scrollRef` (`React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>`) - Scroll container ref.
- `contentRef` (`React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>`) - Content element ref.
- `scrollToBottom` (`ScrollToBottom`) - Scroll to bottom.
- `stopScroll` (`StopScroll`) - Cancel stickiness.
- `isAtBottom` (`boolean`) - At-bottom flag.
- `escapedFromLock` (`boolean`) - Escaped-lock flag.
- `targetScrollTop` (`GetTargetScrollTop | null`) - Mutable override of the target calculator (getter/setter).
- `state` (`StickToBottomState`) - Full animation state.

### Returned By
`useStickToBottomContext`
```

--------------------------------

### useStickToBottom(options?: StickToBottomOptions)

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Hook options for configuring stick-to-bottom behavior.

```APIDOC
## useStickToBottom(options?: StickToBottomOptions)

### Description
Hook that provides stick-to-bottom behavior for a scrollable container. Accepts optional spring animation and behavior options.

### Parameters
- **options** (StickToBottomOptions) - Optional - Configuration object with the following fields:
  - `damping` (number) - Optional - Spring damping (0–1). Default: `0.7`.
  - `stiffness` (number) - Optional - Spring stiffness. Default: `0.05`.
  - `mass` (number) - Optional - Spring mass; higher = slower. Default: `1.25`.
  - `resize` (Animation) - Optional - Animation used for positive content resizes after the initial mount.
  - `initial` (Animation | boolean) - Optional - Animation used on initial mount. When `false`, the hook initializes `isAtBottom` to `false` and does not start pinned to the bottom.
  - `targetScrollTop` (GetTargetScrollTop) - Optional - `(targetScrollTop, context) => number` transform of the target; result is clamped to `[0, targetScrollTop]`.

### Example
```tsx
useStickToBottom({
	damping: 0.5,
	stiffness: 0.08,
	mass: 1.5,
	resize: "smooth",
	initial: { damping: 0.9, stiffness: 0.02, mass: 2 },
	targetScrollTop: (target, { scrollElement }) =>
		Math.min(target, scrollElement.scrollHeight - scrollElement.clientHeight - 50),
});
```
```

--------------------------------

### StickToBottomOptions

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Options for the `useStickToBottom` hook, including spring animation parameters and optional resize, initial, and target scroll top settings.

```APIDOC
## `StickToBottomOptions`

Interface. `src/useStickToBottom.ts:81`

```ts
export interface StickToBottomOptions extends SpringAnimation {
	resize?: Animation;
	initial?: Animation | boolean;
	targetScrollTop?: GetTargetScrollTop;
}
```

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `damping` | `number` | no | `0.7` | Spring damping (inherited from `SpringAnimation`). |
| `stiffness` | `number` | no | `0.05` | Spring stiffness (inherited from `SpringAnimation`). |
| `mass` | `number` | no | `1.25` | Spring mass (inherited from `SpringAnimation`). |
| `resize` | `Animation` | no | — | Animation used for positive content resizes after the initial mount. |
| `initial` | `Animation \| boolean` | no | — | Animation used on initial mount. `false` makes the hook start with `isAtBottom === false` (see the `useState(options.initial !== false)` initializer at `src/useStickToBottom.ts:153`). |
| `targetScrollTop` | `GetTargetScrollTop` | no | — | Transforms the computed bottom target scroll position. |

**Accepted by:** `useStickToBottom(options)`, `StickToBottomProps` (via extension).
```

--------------------------------

### useStickToBottom(options)

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Hook that returns a StickToBottomInstance for managing stick-to-bottom behavior.

```APIDOC
## useStickToBottom(options)

### Description
Hook that returns a `StickToBottomInstance` for managing stick-to-bottom behavior.

### Parameters
- **options** (`StickToBottomOptions`) - Required - Options for the hook.

### Returns
- **StickToBottomInstance** - The instance with methods to control scrolling.

```

--------------------------------

### StickToBottomInstance

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Interface returned by the useStickToBottom hook, exposing refs, scroll controls, and state flags.

```APIDOC
## `StickToBottomInstance`

### Description
Interface returned by `useStickToBottom` hook, providing refs, scroll controls, and state flags for the sticky-to-bottom behavior.

### Fields
- **contentRef** (`React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>`) - Ref for the observed content element.
- **scrollRef** (`React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>`) - Ref for the scroll container.
- **scrollToBottom** (`ScrollToBottom`) - Scroll to bottom; resolves `boolean`.
- **stopScroll** (`StopScroll`) - Cancel stickiness.
- **isAtBottom** (`boolean`) - At-bottom flag (`isAtBottom || isNearBottom` at runtime).
- **isNearBottom** (`boolean`) - Near-bottom flag (within 70px).
- **escapedFromLock** (`boolean`) - Escaped-lock flag.
- **state** (`StickToBottomState`) - Full animation state.

### Returned by
`useStickToBottom`.
```

--------------------------------

### StickToBottomContentProps

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Documentation for the `StickToBottomContentProps` interface, which defines the props for the `StickToBottom.Content` component.

```APIDOC
## `StickToBottomContentProps` / `StickToBottom.ContentProps`

### Description
Interface for the props accepted by the `StickToBottom.Content` component. It extends `React.HTMLAttributes<HTMLDivElement>` except for `children`, which is overridden to accept either a React node or a render-prop function receiving the `StickToBottomContext`.

### Properties
- `children` (`((context: StickToBottomContext) => ReactNode) | ReactNode`) - Required - Content or render-prop for the inner observed element.
- `scrollClassName` (`string`) - Optional - Class name for the outer scroll wrapper element.
- Inherited `React.HTMLAttributes<HTMLDivElement>` - All div attributes except `children`, applied to the inner content element.

### Accepted By
`StickToBottom.Content`
```

--------------------------------

### Import useStickToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Import statement for the useStickToBottom hook from the package entry point.

```ts
import { useStickToBottom } from "use-stick-to-bottom";
```

--------------------------------

### useStickToBottomContext

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/index.md

Hook to consume the StickToBottom context inside a <StickToBottom> component.

```APIDOC
## useStickToBottomContext

### Description
Hook to consume the StickToBottom context inside a <StickToBottom> component.

### Usage
Call inside a component that is a descendant of <StickToBottom>.

### Returns
- **StickToBottomContext** - The context value providing stick-to-bottom state and methods.

```

--------------------------------

### StickToBottom.Content props

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Component that renders the content area with stick-to-bottom behavior.

```APIDOC
## StickToBottom.Content props

### Description
Component that renders the content area with stick-to-bottom behavior.

### Props
- **StickToBottom.ContentProps** - Required - Props for the content component.

### Returns
- **ReactElement** - The rendered element.

```

--------------------------------

### StickToBottomInstance.scrollToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Method to scroll to the bottom of the container.

```APIDOC
## StickToBottomInstance.scrollToBottom

### Description
Method to scroll to the bottom of the container.

### Parameters
- **options** (`ScrollToBottomOptions`) - Required - Options for the scroll behavior.

### Returns
- **Promise<boolean> | boolean** - Whether the scroll was successful.

```

--------------------------------

### useStickToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/index.md

The primary hook that returns a StickToBottomInstance for managing stick-to-bottom behavior.

```APIDOC
## useStickToBottom

### Description
Primary hook that returns a StickToBottomInstance for managing stick-to-bottom behavior.

### Signature
`(options?: StickToBottomOptions) => StickToBottomInstance`

### Parameters
- **options** (StickToBottomOptions) - Optional - Configuration options for the hook.

### Returns
- **StickToBottomInstance** - The hook return value containing state and methods for stick-to-bottom behavior.

```

--------------------------------

### StickToBottomContext.targetScrollTop (set)

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Setter for the target scroll top value in the context.

```APIDOC
## StickToBottomContext.targetScrollTop (set)

### Description
Setter for the target scroll top value in the context.

### Parameters
- **GetTargetScrollTop | null** - Required - The target scroll top value or null.

```

--------------------------------

### Advanced scrollToBottom with wait, ignoreEscapes, and duration

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Demonstrates awaiting scrollToBottom with custom animation options, waiting for in-flight scrolls, ignoring user escapes, and setting a duration. Logs a message if the scroll is cancelled.

```tsx
const { scrollToBottom } = useStickToBottom();

async function revealLatestMessage() {
  const ok = await scrollToBottom({
    animation: { damping: 0.8, stiffness: 0.03, mass: 1.5 },
    wait: true, // finish any in-flight scroll first
    ignoreEscapes: true, // user wheel/touch scroll-up cannot cancel this
    duration: 500, // keep persisting the stick for 500ms after arrival
  });

  if (!ok) {
    console.log("scroll was cancelled before completing");
  }
}
```

--------------------------------

### ScrollToBottomOptions

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Options for the `scrollToBottom` method, allowing control over animation, waiting, escape prevention, scroll position preservation, and duration.

```APIDOC
## `ScrollToBottomOptions`

Type alias. `src/useStickToBottom.ts:87`

```ts
export type ScrollToBottomOptions =
	| ScrollBehavior
	| {
			animation?: Animation;

			/**
			 * Whether to wait for any existing scrolls to finish before
			 * performing this one. Or if a millisecond is passed,
			 * it will wait for that duration before performing the scroll.
			 *
			 * @default false
			 */
			wait?: boolean | number;

			/**
			 * Whether to prevent the user from escaping the scroll,
			 * by scrolling up with their mouse.
			 */
			ignoreEscapes?: boolean;

			/**
			 * Only scroll to the bottom if we're already at the bottom.
			 *
			 * @default false
			 */
			preserveScrollPosition?: boolean;

			/**
			 * The extra duration in ms that this scroll event should persist for.
			 * (in addition to the time that it takes to get to the bottom)
			 *
			 * Not to be confused with the duration of the animation -
			 * for that you should adjust the animation option.
			 *
			 * @default 0
			 */
			duration?: number | Promise<void>;
	  };
```

Two variants: a plain `ScrollBehavior` string (`"auto" | "instant" | "smooth"`, normalized to `{ animation: scrollOptions }`) or an options object.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `animation` | `Animation` | no | — | The animation behavior for this scroll: a scroll behavior string or spring parameters. |
| `wait` | `boolean \| number` | no | `false` | Wait for existing scrolls before starting (`true`), or a millisecond duration to wait. When `true`, an in-flight scroll with the same merged behavior has its promise returned instead of starting a new scroll. |
| `ignoreEscapes` | `boolean` | no | (falsy) | Prevent the user from escaping the scroll by scrolling up (wheel/touch). While set, up-scrolls restore the last position. |
| `preserveScrollPosition` | `boolean` | no | `false` | Only scroll to the bottom if already at the bottom; when `true`, `isAtBottom` is not force-set. |
| `duration` | `number \| Promise<void>` | no | `0` | Extra duration in ms the scroll persists after reaching the target (resolved before the scroll completes if a `Promise`). |

**Accepted by:** `scrollToBottom(scrollOptions)` (both `StickToBottomInstance.scrollToBottom` and `StickToBottomContext.scrollToBottom`).
```

--------------------------------

### StickToBottomState interface

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Interface for the internal state of the stick-to-bottom hook. It includes scroll position fields, animation state, physics properties, and flags for lock and bottom detection. The state is exposed as StickToBottomInstance.state and StickToBottomContext.state.

```ts
export interface StickToBottomState {
	scrollTop: number;
	lastScrollTop?: number;
	ignoreScrollToTop?: number;
	targetScrollTop: number;
	calculatedTargetScrollTop: number;
	scrollDifference: number;
	resizeDifference: number;

	animation?: {
		behavior: "instant" | Required<SpringAnimation>;
		ignoreEscapes: boolean;
		promise: Promise<boolean>;
	};
	lastTick?: number;
	velocity: number;
	accumulated: number;

	escapedFromLock: boolean;
	isAtBottom: boolean;
	isNearBottom: boolean;

	resizeObserver?: ResizeObserver;
}
```

--------------------------------

### Spring integration in scrollToBottom's next()

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

This code snippet shows the spring integration logic used in the animation loop. It updates velocity and position based on damping, stiffness, and mass. The tick delta is normalized by SIXTY_FPS_INTERVAL_MS.

```typescript
state.velocity =
	(behavior.damping * state.velocity +
		behavior.stiffness * state.scrollDifference) /
	behavior.mass;
state.accumulated += state.velocity * tickDelta;
state.scrollTop += state.accumulated;
```

--------------------------------

### StickToBottomInstance.stopScroll

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Method to stop the stick-to-bottom behavior.

```APIDOC
## StickToBottomInstance.stopScroll

### Description
Method to stop the stick-to-bottom behavior.

### Returns
- **void** - No return value.

```

--------------------------------

### `scrollToBottom` — Rejection Paths

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

Details the non-error rejection behavior of `scrollToBottom`, which resolves `false` on cancellation instead of throwing.

```APIDOC
## `scrollToBottom` — Rejection Paths

### Description
`scrollToBottom` never rejects; its `Promise<boolean>` always settles. Cancellation is communicated by the resolved value `false`, not by an exception.

### Resolution Behavior
- Resolves `true` when the scroll completed successfully (final `return state.isAtBottom`, `src/useStickToBottom.ts:382`).
- Resolves `false` when the scroll was cancelled before reaching the target, e.g., `state.isAtBottom` became `false` (user scrolled up / `stopScroll()` was called) during the animation (`src/useStickToBottom.ts:309–313`).

### Consumer Pattern
```tsx
const ok = await scrollToBottom();
if (!ok) {
	console.log("The scroll was cancelled (user scrolled up).");
}
```
```

--------------------------------

### Using StickToBottom Component with ScrollToButton

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/README.md

Use the StickToBottom component in a chat UI. It automatically sticks to the bottom, animates content smoothly, and provides context for child components to check scroll status and programmatically scroll. The ScrollToBottom child uses useStickToBottomContext to show a button when not at the bottom.

```jsx
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()}
      />
    )
  );
}
```

--------------------------------

### Using useStickToBottom Hook with Refs

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/README.md

Use the useStickToBottom hook to attach stick-to-bottom behavior to any existing container. It returns refs for the scroll container and content wrapper. Useful when you need to integrate with a custom component or layout.

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

function Component() {
  const { scrollRef, contentRef } = useStickToBottom();

  return (
    <div style={{ overflow: 'auto' }} ref={scrollRef}>
      <div ref={contentRef}>
        {messages.map((message) => (
          <Message key={message.id} message={message} />
        ))}
      </div>
    </div>
  );
}
```

--------------------------------

### StickToBottomProps

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Props interface for the StickToBottom component, including children, contextRef, instance, and inherited options.

```APIDOC
## `StickToBottomProps`

### Description
Props for the `<StickToBottom>` component, extending `React.HTMLAttributes<HTMLDivElement>` and `StickToBottomOptions`.

### Fields
- **children** (`((context: StickToBottomContext) => ReactNode) | ReactNode`) - Required - Content or render-prop.
- **contextRef** (`React.Ref<StickToBottomContext>`) - Optional - Imperative handle to the context.
- **instance** (`StickToBottomInstance`) - Optional - External hook instance to use instead of the internal one.
- **Inherited from `StickToBottomOptions`**: `mass`, `damping`, `stiffness`, `resize`, `initial`, `targetScrollTop`.
- **Inherited from `React.HTMLAttributes<HTMLDivElement>`**: All div attributes except `children`.

### Accepted by
`<StickToBottom>` component.
```

--------------------------------

### StickToBottomOptions interface

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Defines the options object accepted by the useStickToBottom hook and the <StickToBottom> component. It extends SpringAnimation, so damping, stiffness, and mass are optional and default to the internal defaults.

```ts
export interface StickToBottomOptions extends SpringAnimation {
	resize?: Animation;
	initial?: Animation | boolean;
	targetScrollTop?: GetTargetScrollTop;
}
```

--------------------------------

### <StickToBottom> props

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Component that provides stick-to-bottom behavior to its children.

```APIDOC
## <StickToBottom> props

### Description
Component that provides stick-to-bottom behavior to its children.

### Props
- **StickToBottomProps** - Required - Props for the component.

### Returns
- **ReactElement** - The rendered element.

```

--------------------------------

### StickToBottomContext interface definition

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

Defines the shape of the context object returned by useStickToBottom. Includes refs for the scroll container and observed content, imperative scroll controls, state flags, and a targetScrollTop getter/setter.

```ts
export interface StickToBottomContext {
	contentRef: React.MutableRefObject<HTMLElement | null> &
		React.RefCallback<HTMLElement>;
	scrollRef: React.MutableRefObject<HTMLElement | null> &
		React.RefCallback<HTMLElement>;
	scrollToBottom: ScrollToBottom;
	stopScroll: StopScroll;
	isAtBottom: boolean;
	escapedFromLock: boolean;
	get targetScrollTop(): GetTargetScrollTop | null;
	set targetScrollTop(targetScrollTop: GetTargetScrollTop | null);
	state: StickToBottomState;
}
```

--------------------------------

### scrollToBottom(scrollOptions?: ScrollToBottomOptions)

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Per-call scroll options for the scrollToBottom function.

```APIDOC
## scrollToBottom(scrollOptions?: ScrollToBottomOptions)

### Description
Per-call scroll options for the scrollToBottom function returned by the hook or component.

### Parameters
- **scrollOptions** (ScrollToBottomOptions) - Optional - Options for the scroll-to-bottom call.

### Notes
- The `ScrollToBottomOptions` type is not detailed in the source, but it is used to configure individual scroll calls.
```

--------------------------------

### StickToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/index.md

React component that provides stick-to-bottom functionality. Also carries the namespace member StickToBottom.Content.

```APIDOC
## StickToBottom

### Description
React component that provides stick-to-bottom functionality. Also carries the namespace member StickToBottom.Content.

### Usage
Use as a component in your React tree.

### Namespace Members
- **StickToBottom.Content** - A sub-component for content area.

```

--------------------------------

### useStickToBottomContext hook signature

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

Exact TypeScript signature of the hook. Throws an Error with the message "use-stick-to-bottom component context must be used within a StickToBottom component" when called outside a <StickToBottom> provider.

```ts
export function useStickToBottomContext(): StickToBottomContext {
	const context = useContext(StickToBottomContext);
	if (!context) {
		throw new Error(
			"use-stick-to-bottom component context must be used within a StickToBottom component",
		);
	}

	return context;
}
```

--------------------------------

### scrollToBottom

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Scrolls the container to the bottom. Accepts scroll options and returns a promise that resolves to true if the scroll completed, or false if cancelled.

```APIDOC
## `scrollToBottom`

### Description
Scrolls the container to the bottom. Accepts either a `ScrollBehavior` string or a `ScrollToBottomOptions` object. Returns a promise that resolves to `true` if the scroll completed successfully, or `false` if cancelled (e.g., user scrolled up). If a scroll with the same merged behavior is already running and `wait === true`, the existing animation's promise is returned instead of starting a new one (call coalescing).

### Type Signature
```ts
export type ScrollToBottom = (
	scrollOptions?: ScrollToBottomOptions,
) => Promise<boolean> | boolean;
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `scrollOptions` | `ScrollToBottomOptions` | no | `{}` | See [ScrollToBottomOptions](../types.md#scrolltobottomoptions). |

### Return Value
- `Promise<boolean>` - Resolves `true` as soon as the scroll completed successfully, or `false` if the scroll was cancelled (e.g., the user scrolled up).

### Examples

#### Basic call
```tsx
const { scrollToBottom, isAtBottom } = useStickToBottomContext();

<button onClick={() => scrollToBottom()}>Back to bottom</button>
```

#### Wait for existing scroll, ignore escapes, with an extra duration
```tsx
const { scrollToBottom } = useStickToBottom();

async function revealLatestMessage() {
  const ok = await scrollToBottom({
    animation: { damping: 0.8, stiffness: 0.03, mass: 1.5 },
    wait: true, // finish any in-flight scroll first
    ignoreEscapes: true, // user wheel/touch scroll-up cannot cancel this
    duration: 500, // keep persisting the stick for 500ms after arrival
  });

  if (!ok) {
    console.log("scroll was cancelled before completing");
  }
}
```
```

--------------------------------

### StickToBottom component

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

A React component that wraps useStickToBottom and provides context to descendants. It renders a scrollable div that sticks to the bottom, with configurable spring animation and imperative controls.

```APIDOC
## StickToBottom Component

### Description
A React component that provides sticky-to-bottom behavior for a scrollable container. It wraps the `useStickToBottom` hook and exposes the animation state and controls via React context.

### Signature
```tsx
export function StickToBottom({
	instance,
	children,
	resize,
	initial,
	mass,
	damping,
	stiffness,
	targetScrollTop: currentTargetScrollTop,
	contextRef,
	...props
}: StickToBottomProps): ReactElement
```

### Parameters (Props)

`StickToBottomProps` interface:

```ts
export interface StickToBottomProps
	extends Omit<React.HTMLAttributes<HTMLDivElement>, "children">,
		StickToBottomOptions {
	contextRef?: React.Ref<StickToBottomContext>;
	instance?: StickToBottomInstance;
	children: ((context: StickToBottomContext) => ReactNode) | ReactNode;
}
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `children` | `((context: StickToBottomContext) => ReactNode) \| ReactNode` | yes | — | Content of the wrapper div. If a function, it receives the context object (render-prop pattern). |
| `contextRef` | `React.Ref<StickToBottomContext>` | no | — | Forwarded via `useImperativeHandle` so a parent can read the context instance. |
| `instance` | `StickToBottomInstance` | no | — | An externally created `useStickToBottom()` result; when provided, the component uses it instead of creating its own internal instance. |
| `mass` | `number` (via `StickToBottomOptions`) | no | `1.25` | Spring inertial mass. |
| `damping` | `number` (via `StickToBottomOptions`) | no | `0.7` | Spring damping factor. |
| `stiffness` | `number` (via `StickToBottomOptions`) | no | `0.05` | Spring stiffness. |
| `resize` | `Animation` (via `StickToBottomOptions`) | no | — | Animation used when content grows after the initial mount. |
| `initial` | `Animation \| boolean` (via `StickToBottomOptions`) | no | — | Animation used on initial mount; `false` starts not-at-bottom. |
| `targetScrollTop` | `GetTargetScrollTop` (via `StickToBottomOptions`) | no | — | Function adjusting the computed bottom target scroll position. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` (minus `children`) | no | — | Any other div attributes (`className`, `style`, etc.), spread onto the rendered wrapper `<div>`. |

### Return Type

`ReactElement` — renders:

```tsx
<StickToBottomContext.Provider value={context}>
	<div {...props}>
		{typeof children === "function" ? children(context) : children}
	</div>
</StickToBottomContext.Provider>
```

The wrapper `<div>` carries `...props`.

### Behavior

- Builds a `TargetScrollTop` composed from the `context.targetScrollTop` setter (a mutable ref, `customTargetScrollTop`) falling back to the `targetScrollTop` prop (lines 61–70).
- Creates an internal instance via `useStickToBottom({ mass, damping, stiffness, resize, initial, targetScrollTop })` unless an `instance` prop is supplied (lines 72–83).
- Memoizes a `StickToBottomContext` value from the (internal or supplied) instance (lines 93–112).
- `useImperativeHandle(contextRef, () => context, [context])` (line 129).
- Isomorphic layout effect: if the scroll element's computed `overflow` is `"visible"`, it is forced to `"auto"` so the container is actually scrollable (lines 131–137).

### Example — basic usage

```tsx
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 />
			<ChatBox />
		</StickToBottom>
	);
}

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

	return (
		!isAtBottom && <button onClick={() => scrollToBottom()}>↓</button>
	);
}
```
```

--------------------------------

### DEFAULT_SPRING_ANIMATION constant (internal)

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Internal constant that defines the default animation parameters used by use-stick-to-bottom. Provides the defaults for the optional fields on SpringAnimation: damping (0.7), stiffness (0.05), and mass (1.25). Used by the internal mergeAnimations when merging options.

```ts
const DEFAULT_SPRING_ANIMATION = {
	/**
	 * A value from 0 to 1, on how much to damp the animation.
	 * 0 means no damping, 1 means full damping.
	 *
	 * @default 0.7
	 */
	damping: 0.7,

	/**
	 * The stiffness of how fast/slow the animation gets up to speed.
	 *
	 * @default 0.05
	 */
	stiffness: 0.05,

	/**
	 * The inertial mass associated with the animation.
	 * Higher numbers make the animation slower.
	 *
	 * @default 1.25
	 */
	mass: 1.25,
};
```

--------------------------------

### StickToBottom component signature

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

Exact function signature of the StickToBottom component from src/StickToBottom.tsx. It accepts instance, children, resize, initial, mass, damping, stiffness, targetScrollTop, and contextRef props, plus additional props spread onto the underlying element.

```tsx
export function StickToBottom({
	instance,
	children,
	resize,
	initial,
	mass,
	damping,
	stiffness,
	targetScrollTop: currentTargetScrollTop,
	contextRef,
	...props
}: StickToBottomProps): ReactElement {
```

--------------------------------

### Catching useStickToBottomContext error in a component

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

Shows how to catch the synchronous throw from useStickToBottomContext inside a component render. When the hook throws, the component renders a fallback 'standalone' span; otherwise it uses the context's isAtBottom value.

```tsx
import { useStickToBottomContext } from "use-stick-to-bottom";

function StatusBadge() {
	let context;
	try {
		context = useStickToBottomContext();
	} catch (error) {
		// Rendered outside a <StickToBottom>: no context available.
		return <span>standalone</span>;
	}

	return <span>{context.isAtBottom ? "at bottom" : "scrolled up"}</span>;
}
```

--------------------------------

### Other Documented Failure Conditions

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

Lists documented failure conditions that result in silent state changes rather than exceptions.

```APIDOC
## Other Documented Failure Conditions (No Exceptions, Silent State Changes)

### Description
These conditions do **not** throw; they are handled as state transitions inside the hook.

### Conditions
- **Scroll container has computed `overflow: visible` and no explicit height**: `<StickToBottom>` forces `overflow: auto` on the scroll element (`src/StickToBottom.tsx:131–137`).
- **User scrolls up / wheels up while an animation runs (not `ignoreEscapes`)**: Escape sets `escapedFromLock = true` and `isAtBottom = false`; in-flight promise resolves `false` (`src/useStickToBottom.ts:399–466`, `468–509`).
- **`useStickToBottom` used with elements before refs are attached**: All state getters return `0` defaults (`scrollTop`, `targetScrollTop`) (`src/useStickToBottom.ts:170–220`).
- **Browser overscrolls past target on resize**: `scrollTop` is clamped to `targetScrollTop` (`src/useStickToBottom.ts:533–536`).
```

--------------------------------

### Using stopScroll in a component

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Shows how to use the stopScroll function from the useStickToBottomContext hook. The button click calls stopScroll to immediately stop the container from following new content.

```tsx
const { stopScroll } = useStickToBottomContext();

<button onClick={() => stopScroll()}>Stop following</button>
```

--------------------------------

### ScrollToBottomOptions type definition

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/configuration.md

Defines the per-call options accepted by scrollToBottom. The type is a union of ScrollBehavior or an options object with animation, wait, ignoreEscapes, preserveScrollPosition, and duration properties.

```ts
export type ScrollToBottomOptions =
	| ScrollBehavior
	| {
			animation?: Animation;
			wait?: boolean | number;
			ignoreEscapes?: boolean;
			preserveScrollPosition?: boolean;
			duration?: number | Promise<void>;
	  };
```

--------------------------------

### Error message text

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

The exact error message thrown by useStickToBottomContext when no provider is present. Useful for matching in tests or error handling.

```text
use-stick-to-bottom component context must be used within a StickToBottom component
```

--------------------------------

### StickToBottom.Content

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/StickToBottom.md

The Content component renders the scrollable content area within a StickToBottom container. It accepts children as a function or ReactNode and optional scrollClassName and other HTML attributes.

```APIDOC
## StickToBottom.Content

### Description
Renders the scrollable content area inside a StickToBottom component. It provides a scroll container and an observed content element, and can accept a render-prop function to access the StickToBottom context.

### Signature
```tsx
export function Content({
	children,
	scrollClassName,
	...props
}: ContentProps): ReactElement
```

### Parameters
#### ContentProps
- **children** (`((context: StickToBottomContext) => ReactNode) | ReactNode`) - Required - Rendered inside the observed content (inner) element.
- **scrollClassName** (`string`) - Optional - Class applied to the outer scroll wrapper element.
- **...props** (`React.HTMLAttributes<HTMLDivElement>` minus `children`) - Optional - Attributes for the inner content element.

### Return Type
`ReactElement`. Renders two nested elements:

```tsx
<div
	ref={context.scrollRef}
	style={{ height: "100%", width: "100%", scrollbarGutter: "stable both-edges" }}
	className={scrollClassName}
>
	<div {...props} ref={context.contentRef}>
		{typeof children === "function" ? children(context) : children}
	</div>
</div>
```

The outer div is the scroll container (from `useStickToBottomContext()` — must be inside a `<StickToBottom>`); the inner div is the observed content element with `...props`.

### Example
```tsx
<StickToBottom className="h-[50vh]">
	<StickToBottom.Content className="flex flex-col gap-4" aria-live="polite">
		{messages.map((message) => (
			<Message key={message.id} message={message} />
		))}
	</StickToBottom.Content>
</StickToBottom>
```
```

--------------------------------

### Handling scrollToBottom cancellation result

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/errors.md

Consumer pattern for scrollToBottom's Promise<boolean>. It never rejects; a resolved value of false indicates the scroll was cancelled (e.g., user scrolled up or stopScroll() was called).

```tsx
const ok = await scrollToBottom();
if (!ok) {
	console.log("The scroll was cancelled (user scrolled up).");
}
```

--------------------------------

### useStickToBottom hook signature

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/api-reference/useStickToBottom.md

Exact signature of the useStickToBottom hook from src/useStickToBottom.ts:149. It accepts an optional StickToBottomOptions object and returns a StickToBottomInstance.

```ts
export const useStickToBottom = (
	options: StickToBottomOptions = {},
): StickToBottomInstance => {
```

--------------------------------

### SpringAnimation interface declaration

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Defines the public SpringAnimation type in use-stick-to-bottom. It extends Partial of the internal DEFAULT_SPRING_ANIMATION constant, making all animation fields optional. Use it when configuring animation options; defaults come from the internal constant shown in the expanded snippet.

```ts
export interface SpringAnimation
	extends Partial<typeof DEFAULT_SPRING_ANIMATION> {}
```

--------------------------------

### ScrollToBottom type alias

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Type alias for the function that scrolls to the bottom. It accepts an optional ScrollToBottomOptions (default is {}) and returns a Promise resolving to true when the scroll completes or false when cancelled; the string variant is normalized to an options object first.

```ts
export type ScrollToBottom = (
	scrollOptions?: ScrollToBottomOptions,
) => Promise<boolean> | boolean;
```

--------------------------------

### StopScroll type alias

Source: https://github.com/stackblitz-labs/use-stick-to-bottom/blob/main/_autodocs/types.md

Type alias for the function that cancels stickiness by setting escapedFromLock to true and isAtBottom to false.

```ts
export type StopScroll = () => void;
```
Tokens:
Raw