Hooks

useScrollPosition

Reading progress bars, scroll-linked headers, and back-to-top buttons driven by live offsets.

Import

import { useScrollPosition } from "@zentauri-ui/zentauri-components/hooks/useScrollPosition";

Demo source

Full client component used for this preview (same JSX as below). Adjust paths if you copy outside this app.

"use client";

import { useScrollPosition } from "@zentauri-ui/zentauri-components/hooks/useScrollPosition";
import { HookDemoPanel } from "@/components/preview/hooks/demo-panel";
import { useRef } from "react";

export default function HookDemo() {
  const boxRef = useRef<HTMLDivElement>(null);
  const { x, y } = useScrollPosition({ target: boxRef });
  return (
    <HookDemoPanel title="Interactive demo">
      <p className="mb-4 text-sm text-slate-400">
        Scroll the box — offsets come from a passive scroll listener on the element.
        Omit <span className="font-mono text-cyan-200">target</span> to track the window instead.
      </p>
      <p className="mb-4 font-mono text-sm text-cyan-200">
        x: {Math.round(x)}px, y: {Math.round(y)}px
      </p>
      <div
        ref={boxRef}
        className="h-40 overflow-auto rounded-lg border border-white/10 bg-slate-900/40 p-4 text-sm text-slate-500"
      >
        <div className="w-240">
          {Array.from({ length: 30 }, (_, i) => (
            <p key={i}>Row {i + 1} — keep scrolling in both directions…</p>
          ))}
        </div>
      </div>
    </HookDemoPanel>
  );
}

Interactive demo

Scroll the box — offsets come from a passive scroll listener on the element. Omit target to track the window instead.

x: 0px, y: 0px

Row 1 — keep scrolling in both directions…

Row 2 — keep scrolling in both directions…

Row 3 — keep scrolling in both directions…

Row 4 — keep scrolling in both directions…

Row 5 — keep scrolling in both directions…

Row 6 — keep scrolling in both directions…

Row 7 — keep scrolling in both directions…

Row 8 — keep scrolling in both directions…

Row 9 — keep scrolling in both directions…

Row 10 — keep scrolling in both directions…

Row 11 — keep scrolling in both directions…

Row 12 — keep scrolling in both directions…

Row 13 — keep scrolling in both directions…

Row 14 — keep scrolling in both directions…

Row 15 — keep scrolling in both directions…

Row 16 — keep scrolling in both directions…

Row 17 — keep scrolling in both directions…

Row 18 — keep scrolling in both directions…

Row 19 — keep scrolling in both directions…

Row 20 — keep scrolling in both directions…

Row 21 — keep scrolling in both directions…

Row 22 — keep scrolling in both directions…

Row 23 — keep scrolling in both directions…

Row 24 — keep scrolling in both directions…

Row 25 — keep scrolling in both directions…

Row 26 — keep scrolling in both directions…

Row 27 — keep scrolling in both directions…

Row 28 — keep scrolling in both directions…

Row 29 — keep scrolling in both directions…

Row 30 — keep scrolling in both directions…

What it does

useScrollPosition ships as a small client module you can import from @zentauri-ui/zentauri-components/hooks/useScrollPosition. Use it when the behavior matches your integration without copying utility code.

API notes

Read the interactive demo on this page for the parameters used in typical flows. Refer to TypeScript types exported next to the hook for exhaustive options.

Common use cases

Reuse the same hook in client components across Next.js App Router routes.
Keep server components free of browser APIs; colocate interactive demos in client files.
Compose hooks with Zentauri UI primitives for overlays, forms, and data views.
Align documentation with published @zentauri-ui/zentauri-components/hooks/* paths.

Accessibility

Hooks manipulate behavior, not roles. Pair them with appropriate elements, ARIA attributes, and keyboard handlers so assistive technologies receive a coherent experience.

Next.js integration notes

Keep interactive subtrees in client components. When you only need static copy, leave it in the server layout and pass children into a client boundary that calls the hook.

FAQ

Can I import this hook from a server component?

No. These hooks rely on browser APIs or React client lifecycle. Import them from a file marked with the "use client" directive or from a client child component.

Does the preview site bundle the same code as npm?

The component library app depends on the workspace package. Published builds resolve the same export paths under @zentauri-ui/zentauri-components.

Where should I validate accessibility for hook-driven UI?

Hooks do not replace semantics. Test focus order, labels, and keyboard flows in your real layout with assistive technologies you support.