JavaScript rolar para o topo da página

Use window.scrollTo(0, 0) para levar a página atual ao topo. Para vincular essa ação a um botão, adicione um listener de clique; passe { top: 0, behavior: "smooth"} quando quiser que o navegador anime o movimento.

Use window.scrollTo() para voltar ao topo

Este exemplo cria um botão e o conecta a window.scrollTo(). Coloque o script na página depois que o corpo do documento estiver disponível ou carregue-o com defer, para que o botão possa ser adicionado ao documento. Os pequenos objetos alternativos permitem executar o exemplo em um fixture do Node; no navegador, ele usa o document e o window reais da página.

const inBrowser = typeof document !== "undefined" && typeof window !== "undefined";
const pageDocument = inBrowser ? document : {
  body: {
    append(button) {
      button.click = () => button.listeners.click();
    }
  },
  createElement() {
    return {
      listeners: {},
      addEventListener(name, handler) {
        this.listeners[name] = handler;
      }
    };
  }
};
const pageWindow = inBrowser ? window : {
  scrollTo(x, y) {
    console.log(`scrollTo(${x}, ${y})`);
  }
};

const button = pageDocument.createElement("button");
button.type = "button";
button.textContent = "Back to top";
pageDocument.body.append(button);

button.addEventListener("click", () => {
  pageWindow.scrollTo(0, 0);
});

if (!inBrowser) button.click();

scrollTo(0, 0)

Os dois argumentos são as posições de rolagem horizontal e vertical. Definir ambos como 0 leva a página ao canto superior esquerdo. Use essa forma imediata quando o salto tiver de acontecer na hora, por exemplo, após uma ação breve em que uma animação poderia distrair.

Adicionar rolagem suave com window.scrollTo()

Passe um objeto de opções para window.scrollTo() para solicitar um movimento suave. Esta versão independente usa a mesma pequena alternativa para Node, permitindo demonstrar o manipulador de clique fora de um navegador:

const inBrowser = typeof document !== "undefined" && typeof window !== "undefined";
const pageDocument = inBrowser ? document : {
  body: {
    append(button) {
      button.click = () => button.listeners.click();
    }
  },
  createElement() {
    return {
      listeners: {},
      addEventListener(name, handler) {
        this.listeners[name] = handler;
      }
    };
  }
};
const pageWindow = inBrowser ? window : {
  scrollTo(options) {
    console.log(`scrollTo(top: ${options.top}, behavior: ${options.behavior})`);
  }
};

const button = pageDocument.createElement("button");
button.type = "button";
button.textContent = "Back to top";
pageDocument.body.append(button);

button.addEventListener("click", () => {
  pageWindow.scrollTo({ top: 0, behavior: "smooth" });
});

if (!inBrowser) button.click();

scrollTo(top: 0, behavior: smooth)

A propriedade top define o destino vertical, e behavior: "smooth" solicita que o navegador anime a rolagem. A forma nativa com opções não permite definir uma duração. Se precisar de uma duração específica, use a animação de uma biblioteca ou implemente uma animação personalizada. Uma regra CSS para a página, como html { scroll-behavior: smooth; }, também pode suavizar a rolagem comum, mas, sozinha, não cria um botão nem uma ação para voltar ao topo.

Usar um link âncora para ir ao topo

Uma âncora é uma alternativa útil que não exige script. Atribua um ID ao início da página, por exemplo, <header id="page-top">, e depois crie um link para ele com <a href="#page-top">Back to top</a>. Ao ativar o link, o navegador navega até esse fragmento, atualiza o fragmento da URL e direciona o foco ou a navegação ao destino conforme o comportamento do navegador. Escolha um destino que apareça uma única vez na página; se um cabeçalho fixo o encobrir, ajuste isso com CSS, por exemplo, usando scroll-margin-top no destino.

Usar jQuery para rolar até o topo

Se a página já carrega jQuery, o método animate() pode animar a propriedade scrollTop nos elementos de rolagem do documento. Este exemplo adiciona um botão e associa a animação a ele. No navegador, carregue jQuery antes deste script; se a biblioteca estiver ausente, o exemplo gera um erro claro. A pequena implementação alternativa é usada apenas pelo fixture do Node.

const inBrowser = typeof document !== "undefined" && typeof window !== "undefined";
if (inBrowser && typeof globalThis.jQuery !== "function") {
  throw new Error("jQuery is required for this example. Load jQuery before this script.");
}

const $ = inBrowser ? globalThis.jQuery : (selector, attributes) => {
  if (selector === "<button>") {
    return {
      ...attributes,
      appendTo() { return this; },
      on(name, handler) { this.handler = handler; return this; }
    };
  }
  return {
    animate(properties, duration) {
      console.log(`animate(scrollTop: ${properties.scrollTop}, duration: ${duration})`);
    }
  };
};

const button = $("<button>", {
  type: "button",
  text: "Back to top"
}).appendTo("body");

button.on("click", () => {
  $("html, body").animate({ scrollTop: 0 }, 800);
});

if (!inBrowser) button.handler();

animate(scrollTop: 0, duration: 800)

Aqui, scrollTop: 0 é o destino e 800 é a duração da animação em milissegundos. jQuery é uma dependência opcional; use o método nativo quando a página já não precisar da biblioteca. Se adicionar uma animação personalizada ou outros efeitos de movimento, respeite a preferência do visitante por movimento reduzido.

Escolher a abordagem adequada

Use window.scrollTo(0, 0) para saltar diretamente ao topo com JavaScript. Escolha a forma com opções quando um movimento suave for útil e uma duração controlada pelo navegador for suficiente. Use uma âncora quando a ação tiver de funcionar como navegação comum da página, sem JavaScript. Escolha jQuery quando a biblioteca já fizer parte do projeto e o argumento de duração for adequado à interação. Em uma aplicação de página única, chame o método nativo depois que a rota ou a visualização mudar, caso a aplicação ainda não gerencie a posição de rolagem. Para um link ou botão comum, deixe clara sua finalidade para as tecnologias assistivas e garanta que usuários de teclado possam ativá-lo.