ScrollToTop

Navigation

A threshold-aware return control for the document or a bounded scroll region.

Bounded release guideThreshold disabled stateKeyboard returnReduced-motion scrolling

Responsive viewport — resize the window to explore. Direction and density apply only to this preview. Theme applies to the docs too.

scroll-to-top.tsx

"use client";

import { ScrollToTop } from "@/components/ui/scroll-to-top";
import { useRef } from "react";
export default function ScrollToTopExample() {
  const target = useRef<HTMLDivElement>(null);
  return (
    <div className="w-full max-w-lg space-y-4">
      <div>
        <h3 className="font-semibold">A little further down the page</h3>
        <p className="mt-1 text-sm text-muted-foreground">
          Scroll this guide, then use Back to top to return.
        </p>
      </div>
      <div
        ref={target}
        role="region"
        aria-label="Scrollable release guide"
        tabIndex={0}
        className="h-64 space-y-7 overflow-auto rounded-xl border bg-card p-5 outline-none focus-visible:ring-2 focus-visible:ring-ring"
      >
        {[
          "Start with purpose",
          "Design the details",
          "Make it accessible",
          "Test in context",
          "Share your work",
          "Learn and iterate",
        ].map((title, index) => (
          <section key={title} className="min-h-36 space-y-3">
            <p className="text-xs font-medium text-primary">0{index + 1}</p>
            <h4 className="text-sm font-semibold">{title}</h4>
            <p className="text-sm leading-6 text-muted-foreground">
              Good work takes a little care. Give each step enough room, keep
              the important things clear, and build something your team can make
              their own.
            </p>
          </section>
        ))}
      </div>
      <ScrollToTop targetRef={target} threshold={120} />
    </div>
  );
}

Usage

Use without targetRef to scroll the page, or provide a stable ref to a mounted scrollable HTMLElement. The control remains in layout and is disabled until the threshold is crossed, avoiding appearance-related layout shifts. With a target region, focus returns to that region after activation; give it tabIndex=0. Place the button where it fits your interface, including a fixed position through className if appropriate.

Import

import { ScrollToTop } from "@/components/ui/scroll-to-top";

Shipped as editable source in src/components/ui/scroll-to-top.tsx in both apps. Copy the implementation below when moving it to another project. Copy the complete example from Source code for all imports and state. Add "use client" when using hooks or event handlers. See installation and theming for project setup.

Component source

The complete implementation is included in both apps. It uses the React, Radix, Lucide, and shared-core dependencies already installed in Apex. Keep your project’s semantic theme tokens when reusing it.

src/components/ui/scroll-to-top.tsx

"use client";
import { useEffect, useState, type RefObject } from "react";
import { ArrowUp } from "lucide-react";
import { Button } from "@dashboardpack/core/components/ui/button";
export interface ScrollToTopProps {
  label?: string;
  threshold?: number;
  targetRef?: RefObject<HTMLElement | null>;
  className?: string;
}
export function ScrollToTop({
  label = "Back to top",
  threshold = 200,
  targetRef,
  className,
}: ScrollToTopProps) {
  const [visible, setVisible] = useState(false);
  useEffect(() => {
    const target = targetRef?.current;
    const source = target ?? window;
    const update = () =>
      setVisible(
        (target ? target.scrollTop : window.scrollY) > Math.max(0, threshold),
      );
    source.addEventListener("scroll", update, { passive: true });
    const frame = requestAnimationFrame(update);
    return () => {
      source.removeEventListener("scroll", update);
      cancelAnimationFrame(frame);
    };
  }, [threshold, targetRef]);
  return (
    <Button
      type="button"
      variant="outline"
      size="sm"
      className={className}
      disabled={!visible}
      onClick={() => {
        const target = targetRef?.current;
        const behavior = matchMedia("(prefers-reduced-motion: reduce)").matches
          ? "instant"
          : "smooth";
        (target ?? window).scrollTo({ top: 0, behavior });
        if (target) target.focus({ preventScroll: true });
      }}
    >
      <ArrowUp className="size-4" />
      {label}
    </Button>
  );
}

API reference

Common props and defaults. Slot-specific props are named below; native elements also accept their standard HTML attributes. The component TypeScript definitions are the complete type reference.

ScrollToTop props
Prop	Type / Default	Description
label	`string` Default: Back to top	Visible action text.
threshold	`number` Default: 200	Minimum scroll offset in pixels before enabling.
targetRef	`RefObject<HTMLElement \| null>` Default: window	Stable ref to a mounted scrollable, focusable region.
className	`string` Default: —	Extend the container with semantic theme utilities.

Build with these too

ScrollArea ScrollSpy Button