vue-stick-to-bottom

Designed with AI chat bots in mind, unofficial Vue port of use-stick-to-bottom.

A lightweight Vue 3 component and composable that automatically sticks to the bottom of a scrollable container and smoothly animates content to keep its visual position on screen while new content is being added.

Features

• Does not require overflow-anchor browser-level CSS support (which Safari does not support).
• Can be connected to any existing component using a composable with refs, or simply use the provided component which handles refs for you plus provides context via provide/inject.
• Uses the modern, yet well-supported, ResizeObserver API to detect when content resizes.
  • Supports content shrinking without losing stickiness — not just getting taller.
• Correctly handles Scroll Anchoring. When content above the viewport resizes, the content currently displayed in the viewport won't jump up or down.
• Allows the user to cancel the stickiness at any time by scrolling up.
  • Clever logic distinguishes user scrolling from custom animation scroll events (without debouncing which could cause some events to be missed).
  • Works well on mobile devices too.
• Uses a custom smooth scrolling algorithm with velocity-based spring animations (configurable parameters).
  • Other libraries use easing functions with durations, which don't work well when streaming in new content with variable sizing — common for AI chatbot use cases.
  • scrollToBottom returns a Promise<boolean> which resolves to true once the scroll succeeds, or false if the scroll was cancelled.
• Zero runtime dependencies.
• Tree-shakable ESM build with full TypeScript declarations.

Installation

pnpm add vue-stick-to-bottom
# or: npm install / yarn add

Usage

<StickToBottom> Component

<script setup lang="ts">
import { StickToBottom, useStickToBottomContext } from 'vue-stick-to-bottom'
</script>

<template>
  <StickToBottom class="h-[50vh] relative" resize="smooth" :initial="{ mass: 10 }">
    <div class="flex flex-col gap-4">
      <Message v-for="msg in messages" :key="msg.id" :message="msg" />
    </div>

    <template #overlay>
      <ScrollToBottom />
    </template>

    <template #after>
      <ChatBox />
    </template>
  </StickToBottom>
</template>

The ScrollToBottom child component can use useStickToBottomContext to access state and actions:

<script setup lang="ts">
import { useStickToBottomContext } from 'vue-stick-to-bottom'

const { isAtBottom, scrollToBottom } = useStickToBottomContext()
</script>

<template>
  <button
    v-if="!isAtBottom"
    class="absolute bottom-2 left-1/2 -translate-x-1/2"
    @click="scrollToBottom()"
  >
    ↓ Scroll to bottom
  </button>
</template>

useStickToBottom Composable

For full control over the DOM structure, use the composable directly:

<script setup lang="ts">
import { useStickToBottom } from 'vue-stick-to-bottom'

const { scrollRef, contentRef, isAtBottom, scrollToBottom } = useStickToBottom()
</script>

<template>
  <div ref="scrollRef" style="overflow: auto; height: 50vh;">
    <div ref="contentRef">
      <Message v-for="msg in messages" :key="msg.id" :message="msg" />
    </div>
  </div>

  <button v-if="!isAtBottom" @click="scrollToBottom()">↓</button>
</template>

Slot Props

All slots (default, overlay, after) expose the following props for convenience:

<StickToBottom>
  <template #default="{ isAtBottom, scrollToBottom }">
    <!-- Use slot props directly without useStickToBottomContext -->
  </template>
</StickToBottom>

API

<StickToBottom> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | resize | Animation | Spring | Animation to use when content resizes. | | initial | Animation \| boolean | Spring | Animation for initial scroll. false to start at top. | | targetScrollTop | GetTargetScrollTop | — | Custom function to compute the target scroll position. | | damping | number | 0.7 | Spring damping (0–1). 0 = no damping, 1 = full. | | stiffness | number | 0.05 | Spring stiffness — how fast the animation accelerates. | | mass | number | 1.25 | Spring mass — higher = slower animation. | | anchor | 'auto' \| 'none' | 'auto' | Maps to CSS overflow-anchor. Use 'none' to disable browser scroll anchoring. |

Animation type

type Animation = ScrollBehavior | SpringAnimation
// ScrollBehavior: 'auto' | 'instant' | 'smooth'
// SpringAnimation: { damping?: number; stiffness?: number; mass?: number }

<StickToBottom> Slots

| Slot | Description | |------|-------------| | default | Content inside the scrollable area. | | overlay | Floats above the scrollable content (e.g. scroll-to-bottom button). Positioned within the relative wrapper. | | after | Outside the scroll area entirely (e.g. input box, external controls). |

All slots receive { isAtBottom, isNearBottom, escapedFromLock, scrollToBottom, stopScroll } as slot props.

useStickToBottom(options?)

Returns:

| Property | Type | Description | |----------|------|-------------| | scrollRef | Ref<HTMLElement \| null> | Template ref for the scroll container. | | contentRef | Ref<HTMLElement \| null> | Template ref for the content wrapper. | | isAtBottom | Ref<boolean> | Whether the container is at (or very near) the bottom. | | isNearBottom | Ref<boolean> | Whether the container is within ~70px of the bottom. | | escapedFromLock | Ref<boolean> | Whether the user has scrolled up to cancel stickiness. | | scrollToBottom | ScrollToBottom | Programmatically scroll to the bottom. | | stopScroll | StopScroll | Stop the current scroll animation and release the lock. | | setOptions | (options) => void | Update engine options at runtime. |

scrollToBottom(options?)

type ScrollToBottomOptions =
  | ScrollBehavior
  | {
      animation?: Animation
      wait?: boolean | number     // Wait for existing scrolls or delay in ms
      ignoreEscapes?: boolean     // Prevent user from cancelling this scroll
      preserveScrollPosition?: boolean  // Only scroll if already at bottom
      duration?: number | Promise<void> // Extra duration to maintain the scroll
    }

Returns Promise<boolean> — resolves to true if scroll completed, false if cancelled.

useStickToBottomContext()

Call inside a child component of <StickToBottom> to access the context via inject. Throws if used outside the component tree.

Demo

Run the built-in demo:

pnpm dev

This opens a playground showcasing smooth vs instant columns, a speed slider, a floating scroll-to-bottom button, and stop-scroll controls.

Credits

This is a Vue 3 port of use-stick-to-bottom by Sam Denty / StackBlitz.

License

MIT