useScrollToTop — Desplaza la ventana al inicio y muestra un botón "volver al inicio"

Receta

import { useState, useEffect, useCallback } from "react";
 
interface UseScrollToTopOptions {
  /** Distancia de desplazamiento (px) antes de que aparezca el botón. Por defecto: 300 */
  threshold?: number;
  /** Usa desplazamiento suave. Por defecto: true */
  smooth?: boolean;
}
 
interface UseScrollToTopReturn {
  /** Si la página se ha desplazado más allá del umbral */
  isVisible: boolean;
  /** Llama esto para desplazarse al inicio */
  scrollToTop: () => void;
  /** Posición de desplazamiento actual */
  scrollY: number;
}
 
function useScrollToTop(
  options: UseScrollToTopOptions = {}
): UseScrollToTopReturn {
  const { threshold = 300, smooth = true } = options;
  const [isVisible, setIsVisible] = useState(false);
  const [scrollY, setScrollY] = useState(0);
 
  useEffect(() => {
    const handleScroll = () => {
      const y = window.scrollY;
      setScrollY(y);
      setIsVisible(y > threshold);
    };
 
    // Verifica la posición inicial
    handleScroll();
 
    window.addEventListener("scroll", handleScroll, { passive: true });
    return () => window.removeEventListener("scroll", handleScroll);
  }, [threshold]);
 
  const scrollToTop = useCallback(() => {
    window.scrollTo({
      top: 0,
      behavior: smooth ? "smooth" : "instant",
    });
  }, [smooth]);
 
  return { isVisible, scrollToTop, scrollY };
}

Cuándo usarlo: Tienes una página larga y deseas dar a los usuarios una forma rápida de volver al inicio, con el botón apareciendo solo después de que hayan desplazado la página una distancia significativa.

Ejemplo Funcional

"use client";
 
function BackToTopButton() {
  const { isVisible, scrollToTop } = useScrollToTop({
    threshold: 400,
    smooth: true,
  });
 
  return (
    <button
      onClick={scrollToTop}
      aria-label="Scroll to top"
      style={{
        position: "fixed",
        bottom: 24,
        right: 24,
        width: 48,
        height: 48,
        borderRadius: "50%",
        border: "none",
        background: "#111",
        color: "#fff",
        fontSize: 20,
        cursor: "pointer",
        opacity: isVisible ? 1 : 0,
        transform: isVisible ? "translateY(0)" : "translateY(16px)",
        transition: "opacity 0.3s, transform 0.3s",
        pointerEvents: isVisible ? "auto" : "none",
      }}
    >
      ↑
    </button>
  );
}
 
function LongPage() {
  return (
    <div>
      <h1>Título del Artículo</h1>
      {Array.from({ length: 50 }, (_, i) => (
        <p key={i}>Párrafo {i + 1} del contenido...</p>
      ))}
      <BackToTopButton />
    </div>
  );
}

Lo que esto demuestra:

• El botón se desvanece después de desplazarse más allá de 400 px
• Al hacer clic en el botón, la página se desplaza suavemente al inicio
• Las transiciones CSS manejan la animación de mostrar/ocultar
• pointerEvents: "none" previene que el botón invisible bloquee clics
• aria-label asegura accesibilidad del lector de pantalla

Análisis Profundo

Cómo Funciona

• Un único listener de evento scroll (con { passive: true } para rendimiento) rastrea window.scrollY.
• isVisible se pone en true cuando scrollY supera el umbral, dando al componente consumidor un booleano reactivo para renderizar.
• scrollToTop llama a window.scrollTo con behavior: "smooth" para una animación de desplazamiento suave nativa.
• La opción passive: true le dice al navegador que el handler no llamará a preventDefault, permitiendo optimizaciones de rendimiento de desplazamiento.
• La posición inicial se verifica inmediatamente en el efecto para que el estado del botón sea correcto al montar (por ejemplo, si el usuario actualiza la página en el medio).

Parámetros y Valores de Retorno

Variaciones

Handler de desplazamiento con throttle: Para páginas con renderizado pesado, envuelve el handler de desplazamiento con useThrottledCallback para reducir actualizaciones de estado:

const handleScroll = useThrottledCallback(() => {
  setScrollY(window.scrollY);
  setIsVisible(window.scrollY > threshold);
}, 100);

Desplazarse a elemento: Extiende para desplazarse a cualquier ref de elemento en lugar del inicio:

const scrollToElement = useCallback((ref: React.RefObject<HTMLElement>) => {
  ref.current?.scrollIntoView({ behavior: smooth ? "smooth" : "instant" });
}, [smooth]);

Notas de TypeScript

• El objeto de opciones utiliza una interfaz con propiedades opcionales, dando autocompletado de IDE.
• El tipo de retorno es una interfaz nombrada para fácil reutilización y documentación.
• No se necesitan genéricos ya que todos los tipos son concretos.

Trampa Oculta

• Rendimiento en páginas pesadas — Actualizar el estado en cada evento de desplazamiento puede causar tartamudeo en páginas complejas. Solución: Throttle del handler o usa requestAnimationFrame.
• Crash de SSR — window no está disponible durante la renderización del lado del servidor. Solución: El useEffect solo se ejecuta en el cliente, por lo que el hook es seguro para SSR tal como está escrito. El estado por defecto (isVisible: false) es correcto para SSR.
• Desplazamiento suave no soportado — Los navegadores muy antiguos ignoran behavior: "smooth". Solución: La página aún se desplaza instantáneamente, lo cual es un alternativa aceptable.
• Conflictos de posición fija — Un botón fijo puede superponerse con barras de navegación móvil. Solución: Ajusta el valor bottom o añade z-index para capas correctamente.

Alternativas

Preguntas Frecuentes

const handleScroll = useThrottledCallback(() => {
  setScrollY(window.scrollY);
  setIsVisible(window.scrollY > threshold);
}, 100);

interface Props {
  scrollOptions: UseScrollToTopOptions;
}
 
function MyComponent({ scrollOptions }: Props) {
  const result: UseScrollToTopReturn = useScrollToTop(scrollOptions);
}

const scrollToElement = useCallback(
  (ref: React.RefObject<HTMLElement>) => {
    ref.current?.scrollIntoView({
      behavior: smooth ? "smooth" : "instant",
    });
  },
  [smooth]
);

Relacionado

• useThrottle — throttle del handler de desplazamiento
• useEventListener — binding de eventos declarativo
• useIntersectionObserver — disparadores basados en desplazamiento alternativos