useScrollToTop - Rola a janela para o topo e mostra um botão "voltar ao topo"

Receita

import { useState, useEffect, useCallback } from "react";
 
interface UseScrollToTopOptions {
  /** Distância de rolagem (px) antes do botão aparecer. Padrão: 300 */
  threshold?: number;
  /** Usa rolagem suave. Padrão: true */
  smooth?: boolean;
}
 
interface UseScrollToTopReturn {
  /** Se a página rolou além do limite */
  isVisible: boolean;
  /** Chame isso para rolar até o topo */
  scrollToTop: () => void;
  /** Posição atual de rolagem */
  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 a posição 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 };
}

Quando usar isso: Você tem uma página longa e quer dar aos usuários uma maneira rápida de retornar ao topo, com o botão aparecendo apenas depois que eles rolarem uma distância significativa.

Exemplo 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 do Artigo</h1>
      {Array.from({ length: 50 }, (_, i) => (
        <p key={i}>Parágrafo {i + 1} de conteúdo...</p>
      ))}
      <BackToTopButton />
    </div>
  );
}

O que isso demonstra:

• O botão aparece gradualmente após rolar 400 px
• Clicar no botão rola suavemente para o topo da página
• Transições CSS cuidam da animação de mostrar/ocultar
• pointerEvents: "none" impede que o botão invisível bloqueie cliques
• aria-label garante acessibilidade para leitores de tela

Análise Detalhada

Como Funciona

• Um único listener de evento scroll (com { passive: true } para desempenho) rastreia window.scrollY.
• isVisible muda para true quando scrollY excede o threshold, dando ao componente consumidor um booleano reativo para renderização.
• scrollToTop chama window.scrollTo com behavior: "smooth" para uma animação de rolagem suave nativa.
• A opção passive: true informa ao navegador que o manipulador não chamará preventDefault, permitindo otimizações de desempenho de rolagem.
• A posição inicial é verificada imediatamente no useEffect para que o estado do botão esteja correto na montagem (por exemplo, se o usuário atualizar a página no meio dela).

Parâmetros e Valores de Retorno

Variações

Manipulador de scroll com throttling: Para páginas com renderização pesada, envolva o manipulador de scroll com useThrottledCallback para reduzir as atualizações de estado:

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

Scroll para elemento: Estenda para rolar para qualquer ref de elemento em vez do topo:

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

Notas TypeScript

• O objeto de opções usa uma interface com propriedades opcionais, fornecendo autocompletar no IDE.
• O tipo de retorno é uma interface nomeada para fácil reutilização e documentação.
• Nenhum genérico é necessário, pois todos os tipos são concretos.

Armadilhas

• Desempenho em páginas pesadas - Atualizar o estado a cada evento de scroll pode causar travamentos em páginas complexas. Correção: Use throttling no manipulador ou requestAnimationFrame.
• Falha de SSR - window não está disponível durante a renderização do lado do servidor. Correção: O useEffect só é executado no cliente, então o hook é seguro para SSR como está escrito. O estado padrão (isVisible: false) está correto para SSR.
• Scroll suave não suportado - Navegadores muito antigos ignoram behavior: "smooth". Correção: A página ainda rola instantaneamente, o que é um fallback aceitável.
• Conflitos de posição fixa - Um botão fixo pode sobrepor barras de navegação móveis. Correção: Ajuste o valor de bottom ou adicione z-index para organizar corretamente.

Alternativas

FAQs

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]
);

Relacionados

• useThrottle - limita a taxa de atualização do manipulador de scroll
• useEventListener - vinculação declarativa de eventos
• useIntersectionObserver - gatilhos alternativos baseados em scroll