scroll

Track the scroll offset, edges, and direction of an element or window.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useScroll, useWindowScroll } from "@vizejs/composable/scroll";

Try it

Navigate a scrollable preparation guide

Connect native scrolling, writable vertical offset, edge state, and keyboard controls to one bounded guide preview.

Open the interactive example

What to observe: Scroll the read-only preparation preview, or activate Next guide section. Its actual vertical offset changes and Previous becomes available. Continue to the end: Next disables when the element reaches its bottom. Return to the beginning resets the offset and disables Previous. The surrounding document is not the observed target.

useScroll receives the real HTMLTextAreaElement template ref. Assigning y and calling scrollTo move that element; its real client and scroll dimensions determine arrivedState. Native scroll events update activity, which settles on scrollend or the 200 ms idle fallback. Read-only text still supports ordinary selection and keyboard scrolling. SSR starts at zero with the top/left edges arrived, no bottom/right arrival, and no browser listeners. Client attachment follows mounted state; scope disposal removes listeners and the idle timer. These controls navigate local content and do not request or save data.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useId, useTemplateRef } from "vue";
import { useScroll } from "@vizejs/composable/scroll";

const previewId = useId();
const preview = useTemplateRef<HTMLTextAreaElement>("preview");
const guide = [
  "Workshop preparation guide",
  "",
  "1. Install the Vue tooling in your existing project.",
  "Keep the dependency changes separate from application changes.",
  "",
  "2. Compile a representative component.",
  "Check its emitted behavior and its diagnostics.",
  "",
  "3. Review keyboard interaction.",
  "Use the native controls before adding custom shortcuts.",
  "",
  "4. Check a narrow viewport.",
  "Verify that content wraps and controls stay reachable.",
  "",
  "5. Publish the verified result.",
  "Keep the source and the demonstrated behavior aligned.",
].join("\n");
const { y, arrivedState, isScrolling, scrollTo } = useScroll(preview);
</script>

<template>
  <div class="composable-example">
    <label :for="previewId">Preparation guide preview</label>
    <textarea :id="previewId" ref="preview" class="guide-preview" :value="guide" readonly />
    <div class="example-actions">
      <button type="button" :disabled="arrivedState.top" @click="() => (y = y - 120)">
        Previous guide section
      </button>
      <button type="button" :disabled="arrivedState.bottom" @click="() => (y = y + 120)">
        Next guide section
      </button>
      <button type="button" @click="() => scrollTo({ top: 0 })">Return to the beginning</button>
    </div>
    <output aria-live="polite">
      Vertical offset: {{ Math.round(y) }} pixels · At beginning:
      {{ arrivedState.top ? "yes" : "no" }} · At end: {{ arrivedState.bottom ? "yes" : "no" }}
    </output>
    <p>Scrolling activity: {{ isScrolling ? "active" : "idle" }}</p>
    <p>
      Scroll the native read-only preview or use the buttons. Assigning the writable y ref scrolls
      this element; edge flags follow its real dimensions and disable the corresponding controls.
      This preview does not scroll the surrounding documentation page.
    </p>
  </div>
</template>

<style scoped>
.guide-preview {
  box-sizing: border-box;
  inline-size: 100%;
  block-size: 140px;
  resize: none;
  padding: 12px;
  line-height: 1.6;
}
</style>

Runtime contract

API

useScroll

Track the scroll offset, edges, and direction of an element or window. During server rendering (or while the target is unresolved) offsets are 0, the top/left edges report arrived, and the bottom/right edges do not — matching an unscrolled page, so hydration is stable. The scroll listener is passive and removed together with the idle timer when the owning reactive scope stops. Inside a component the host is read after mounting, so hydration renders the server fallback first and never mismatches.

function useScroll( target: MaybeRefOrGetter<ScrollTargetValue>, options: UseScrollOptions = {}, ): ScrollControls

useWindowScroll

Track the document scroll position. Equivalent to useScroll with the window as target, so it shares its SSR-stable defaults and scope-bound cleanup.

function useWindowScroll(options: UseWindowScrollOptions = {}): ScrollControls

Types

ScrollMetrics

Scroll extents shared by elements and the document root element.

ScrollWindowHost

Window-like scroll container accepted by useScroll.

ScrollEdges

Per-edge boolean state.

ScrollOffset

Per-edge distance thresholds in CSS pixels.

UseScrollOptions

Options for useScroll.

ScrollControls

Reactive scroll state returned by useScroll.

UseWindowScrollOptions

Options for useWindowScroll.