Skip to content

ScrollToTop

SM · 950B gzip budget

Button that scrolls to page top with reduced motion support.

Category
Navigation
Budget
sm, single-purpose control
External runtime
React / React DOM only
axe fixtureSSR rendersource scanbundle budget

Preview

Live fixture
Preview locale

Try the component here. Locale-aware formatting and direction follow the selected language; example content and labels are not automatically translated. Overlay demos use interactive launchers.

Install

npx shadcn@latest add https://gear5-ui.vercel.app/r/scroll-to-top.json

Copies the source into your project.

New here? Set up Tailwind and import aliases first →

Source & props

Edit on GitHub ↗

Prop types and inline documentation are included below. This is repository source; the installer rewrites shared imports for your project.

"use client";

import React, { useCallback, useEffect, useState } from "react";

export interface ScrollToTopProps {
  threshold?: number;
  className?: string;
  ariaLabel?: string;
  children?: React.ReactNode;
}

export function ScrollToTop({
  threshold = 300,
  className = "",
  ariaLabel = "Scroll to top",
  children,
}: ScrollToTopProps) {
  const [visible, setVisible] = useState(false);

  useEffect(() => {
    const handleScroll = () => {
      setVisible(window.scrollY > threshold);
    };

    window.addEventListener("scroll", handleScroll, { passive: true });
    return () => window.removeEventListener("scroll", handleScroll);
  }, [threshold]);

  const scrollToTop = useCallback(() => {
    window.scrollTo({ top: 0, behavior: "smooth" });
  }, []);

  const handleKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      if (e.key === "Enter" || e.key === " ") {
        e.preventDefault();
        scrollToTop();
      }
    },
    [scrollToTop]
  );

  if (!visible) return null;

  return (
    <button
      type="button"
      aria-label={ariaLabel}
      className={className}
      onClick={scrollToTop}
      onKeyDown={handleKeyDown}
      style={{
        position: "fixed",
        bottom: "1.5rem",
        insetInlineEnd: "1.5rem",
        width: "3rem",
        height: "3rem",
        borderRadius: "50%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        background: "var(--color-primary, #3b82f6)",
        color: "#fff",
        border: "none",
        cursor: "pointer",
        boxShadow: "0 2px 8px rgba(0, 0, 0, 0.2)",
        transition: "opacity 0.2s, transform 0.2s",
        opacity: visible ? 1 : 0,
        transform: visible ? "translateY(0)" : "translateY(8px)",
        zIndex: 50,
      }}
    >
      {children ?? (
        <span aria-hidden="true" style={{ fontSize: "1.25rem", lineHeight: 1 }}>
          ↑
        </span>
      )}
    </button>
  );
}

What CI checks

Quality contract
  • Bundled, minified and gzipped against its tier budget
  • Audited by axe in the state previewed above
  • Rendered through react-dom/server with no browser globals
  • Scanned for network calls, dangerous sinks, and unguarded animation
← All components