Neste artigo
A paginação no tema WordPress é o conjunto de links numerados que divide uma lista longa de posts em páginas navegáveis. Ela aparece nos templates de arquivo (archive.php, index.php, category.php) quando o número de posts ultrapassa o limite definido em Configurações > Leitura. Sem paginação, o visitante vê só os primeiros posts e os demais ficam inacessíveis sem busca. Neste guia você vai configurar a paginação com funções reais do core, tratar o caso do WP_Query custom e decidir entre código e plugin. Para o panorama completo de personalização, veja o hub de conteúdos sobre temas WordPress da FULL.
Diagnóstico rápido: Por que some a paginação no tema WordPress
A paginação no tema WordPress desaparece por três causas que respondem por boa parte dos tickets de tema no suporte da FULL: o template de arquivo não chama função de navegação, o WP_Query custom ignora a variável paged, ou o limite de posts por página em Configurações > Leitura está alto (padrão 10). A tabela abaixo cruza sintoma, causa raiz e correção.
| Sintoma | Causa raiz | Ação corretiva |
|---|---|---|
| Nenhum link de página aparece | Template de arquivo sem chamada de função | Adicionar the_posts_pagination() após o loop |
| Página 2 retorna erro 404 | WP_Query custom sem o parâmetro paged | Passar ‘paged’ => get_query_var(‘paged’) no WP_Query |
| Tudo cabe em uma página só | Posts por página alto em Leitura | Reduzir o limite em Configurações > Leitura |
O erro 404 na página 2 é o mais comum em temas customizados. Ele acontece porque o WP_Query não sabe em qual página está, então o WordPress monta a query da página 1 e devolve um conteúdo que a URL /page/2/ não reconhece como válido. Das três causas, só esse 404 exige editar a query do tema; as outras duas se resolvem em uma função ou num campo do painel.
Passo a passo: Adicionar paginação no tema WordPress
Adicionar paginação no tema WordPress leva cerca de 5 minutos no loop principal e usa funções nativas, sem plugin. A função the_posts_pagination() foi introduzida no core na versão 4.1, em , e desde então é o método recomendado pelo Theme Handbook. Os passos abaixo cobrem o caso mais frequente, que é a navegação no index.php ou archive.php do tema, sempre depois de fechar o loop principal do WordPress.
Passo 1: Localize o fim do loop no template
Abra index.php ou archive.php no editor de arquivos do tema e encontre a linha endwhile; que fecha o while ( have_posts() ). A navegação de paginação entra logo após esse endwhile; e antes do else: que trata a ausência de posts. Esse posicionamento garante que os links só apareçam quando há posts listados.
Passo 2: Chame the_posts_pagination com argumentos
Insira the_posts_pagination() depois do endwhile;. Os argumentos mid_size (padrão 2) controlam quantos números aparecem de cada lado da página atual, e prev_text/next_text definem os rótulos. Um exemplo enxuto: the_posts_pagination( array( 'mid_size' => 1, 'prev_text' => 'Anterior', 'next_text' => 'Próxima' ) );. A função ecoa a saída de get_the_posts_pagination() direto no template.
Passo 3: Ajuste o número de posts por página
Vá em Configurações > Leitura e defina “As páginas do blog devem mostrar no máximo”. O padrão é 10. Esse valor alimenta a propriedade max_num_pages da query, que the_posts_pagination() lê para saber quantas páginas gerar. Se o total de posts não passar desse número, nenhum link aparece, e isso não é bug.
Passo 4: Estilize a navegação com CSS
A saída fica dentro de <nav class="navigation pagination">, com cada número em <a class="page-numbers"> e o atual em <span class="page-numbers current">. Mire essas classes no style.css do tema para aplicar espaçamento, cor e estado ativo. Como a marcação é padronizada, o mesmo CSS serve para qualquer template de arquivo do tema.
Passo 5: Valide a navegação na página 2
Acesse /page/2/ do arquivo e confirme que o conteúdo muda e que a página 2 não devolve 404. Se o loop for o principal, funciona direto. Se for um WP_Query custom, o erro 404 indica o parâmetro paged ausente, que o próximo H2 resolve com get_query_var.
Paginação em wp_query custom: O detalhe do paged
Em uma WP_Query própria, a paginação no tema WordPress quebra na página 2 porque a query não recebe a página atual. A correção tem uma linha: declarar 'paged' => get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1 dentro dos argumentos do WP_Query. Sem isso, a query devolve sempre o primeiro conjunto e a URL /page/N/ retorna 404, o que confunde até quem programa PHP no WordPress há anos.
Há uma armadilha de nomenclatura aqui. A variável é paged (com “d”) para o loop de arquivo e o loop principal, mas é page (sem “d”) quando a paginação ocorre dentro de um post ou página estática usando a tag <!--nextpage-->. Trocar uma pela outra produz exatamente o mesmo 404 silencioso, e o pior é que a página 1 carrega normalmente, então o problema só aparece quando alguém clica para a segunda página. Em um functions.php de tema custom, mantenha as duas variáveis mapeadas para não depurar no escuro, prática que documentamos junto ao arquivo functions.php do tema.
The_posts_pagination ou paginate_links: Qual usar
Ao montar a paginação no tema WordPress, a escolha entre the_posts_pagination() e paginate_links() define o controle sobre a marcação. A primeira é um atalho de alto nível para o loop principal e exige uma linha. A segunda, no core desde a versão 2.1, retorna os links como string ou array e aceita o argumento type, o que dá controle fino sobre o HTML.
O argumento type aceita três valores: plain (string com quebras de linha), list (envolve tudo em <ul>) e array (devolve cada link separado para você montar a estrutura). Para listas de posts de um WP_Query custom, paginate_links() com 'total' => $query->max_num_pages dá o resultado mais previsível, porque você passa o total de páginas na mão em vez de depender da query global.
Quatro ferramentas reais compõem esse terreno: the_posts_pagination() e paginate_links() no core, o plugin WP-PageNavi para quem quer painel visual, e a WP_Query como fonte do max_num_pages. Em temas de blocos (FULL Site Editing), a navegação vira o bloco Query Pagination, que por baixo dos panos também chama paginate_links(). Quem migra de criação de temas WordPress clássicos para FSE encontra o mesmo motor com interface nova.
WP-PageNavi e plugins: Quando o código não compensa
O plugin WP-PageNavi entrega a paginação no tema WordPress sem editar PHP, e faz sentido em cenários específicos. Ele troca a função posts_nav_link() por uma navegação numerada configurável por painel, com mais de um milhão de instalações ativas no diretório do WordPress.org. Para um cliente que não toca em código, é um atalho legítimo.
A decisão segue a regra que repetimos no suporte da FULL: plugin de paginação se justifica quando ninguém da equipe edita o tema; caso contrário, the_posts_pagination() entrega o mesmo resultado sem peso adicional. Adicionar um plugin a mais carrega CSS e JS extras em toda página de arquivo, e em sites grandes um plugin a menos ajuda o desempenho do blog mensurado no PageSpeed Insights. A escolha não é só técnica, é de quem vai manter o site no dia a dia.
Acelere a personalização do seu tema com a FULL
Editar archive.php, ajustar o WP_Query e estilizar a navegação são tarefas que pedem um ambiente com os plugins certos já ativos. No plano PRO da FULL, por R$849, você ativa Elementor PRO, Astra PRO, Crocoblock e outros 14 plugins premium com um clique, o que dá menos de R$85 por site quando você gerencia uma carteira de 10 ou mais projetos. A gente vê no suporte que muito tempo de tema se perde licenciando plugin a plugin em cada instalação, repetindo o mesmo cadastro de licença dezenas de vezes. Com a ativação centralizada, esse trabalho manual some: o Astra PRO entra como tema base e o Crocoblock cobre os templates de arquivo onde a paginação vive. Conheça os planos da FULL e centralize a ativação dos plugins de tema em um painel só, sem repetir licenças site a site.
Legenda: a navegação numerada gerada por the_posts_pagination() comprova que o template de arquivo lê o max_num_pages corretamente.
Perguntas frequentes sobre paginação no tema WordPress
Por que a página 2 do meu arquivo retorna erro 404?
O erro 404 na página 2 acontece quando um WP_Query custom não recebe o parâmetro paged. O WordPress monta a query da página 1 e a URL /page/2/ deixa de existir para aquele template. A correção é declarar ‘paged’ => get_query_var(‘paged’) nos argumentos do WP_Query. No loop principal isso já vem resolvido, então o problema só aparece em queries próprias dentro do tema.
É possível adicionar paginação no tema sem instalar nenhum plugin?
Sim, a paginação no tema WordPress funciona só com funções do core, sem plugin. Basta chamar the_posts_pagination() depois do endwhile do loop no archive.php ou index.php. A função existe desde a versão 4.1 e gera a navegação numerada automaticamente. Plugins como WP-PageNavi são opcionais e fazem sentido apenas quando ninguém da equipe edita o código do tema diretamente.
Qual a diferença entre the_posts_pagination e paginate_links?
A função the_posts_pagination() é um atalho de alto nível que ecoa a navegação do loop principal em uma linha. A paginate_links(), no core desde a versão 2.1, retorna os links como string ou array e aceita o argumento type com os valores plain, list e array. Use paginate_links() quando precisar de controle sobre a marcação ou quando paginar um WP_Query custom com ‘total’ => max_num_pages.
Como controlar quantos números de página aparecem na navegação?
O argumento mid_size define quantos números aparecem de cada lado da página atual, com padrão 2, e o end_size define quantos aparecem nas pontas, com padrão 1. Passe mid_size => 1 para uma navegação mais enxuta. Ambos os argumentos valem tanto para the_posts_pagination() quanto para paginate_links(), porque a primeira repassa os parâmetros para a segunda por baixo dos panos.
A paginação muda em temas de blocos com FULL Site Editing?
Em temas de blocos com FULL Site Editing, a paginação vira o bloco Query Pagination, configurado no editor visual em vez do PHP. Por baixo dos panos, esse bloco também chama paginate_links(), então o comportamento de página e o parâmetro paged seguem a mesma lógica do tema clássico. Quem mantém os dois tipos de tema usa o mesmo raciocínio de max_num_pages para depurar a navegação.
Próximos passos para dominar os templates do tema
Configurar a paginação no tema WordPress se resume a uma decisão: usar the_posts_pagination() no loop principal, paginate_links() no WP_Query custom, ou o bloco Query Pagination no FULL Site Editing. Os três leem o mesmo max_num_pages, então depurar a página 2 é sempre verificar o parâmetro paged. Com a navegação resolvida, o próximo terreno é a estrutura do template, do child theme à template tag certa para cada arquivo, tema que a categoria de temas WordPress da FULL aprofunda. Para continuar aprendendo, o FULL Academy reúne tutoriais, guias e reviews de tema em um só lugar.
