Hugo Pagination with Paginator Object

What is Pagination?

Pagination is the process of dividing a document into discrete pages. On a website, it's the familiar "1, 2, 3, Next" navigation you see at the bottom of blog indexes, product catalogs, or search results.

Proper pagination improves site usability, reduces page load times, and helps search engines crawl your content more efficiently.

To get familiar with Hugo's terminology and a few key configuration settings, let's start with the official documentation.

As you saw in the reading, you can set the number of items per page globally in your hugo.toml file:

// hugo.toml

[pagination]
  pagerSize = 5

With this setting, any paginated list will default to showing 5 items per page.

Implementing Pagination in Your Template

Now for the implementation. Hugo makes pagination straightforward by providing a powerful Paginator object. You create this object in your template, and it gives you everything you need: the list of items for the current page, and all the information required to build the navigation links.

There are two slightly different methods to create the paginator, .Paginator and .Paginate. We will focus on .Paginate because it's more flexible and allows you to modify or filter the content before paginating it, which will be useful later.

Let's modify the list template we conceptualized in the last lesson.

Before (listing all pages):

{{/* layouts/_default/list.html */}}

{{ range .Pages }}
  <article>
    <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
  </article>
{{ end }}

After (implementing pagination):

{{/* layouts/_default/list.html */}}

{{ $paginator := .Paginate .Pages }}
{{ range $paginator.Pages }}
  <article>
    <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
  </article>
{{ end }}

{{/* We'll add navigation here */}}

Notice the two key changes:

1. We call .Paginate .Pages and store the result in a variable called $paginator. This creates the Paginator object. You can also override the default page size here, for example: .Paginate .Pages 10.
2. Our range loop now iterates over $paginator.Pages, not .Pages. This ensures it only loops through the items for the current page.

Adding Pagination Controls: The Easy Way

A paginated list is useless without navigation. Hugo provides an embedded partial that makes adding navigation incredibly simple.

By adding just one line to our template, we get a fully functional navigation element.

Complete list template with pagination:

{{/* layouts/_default/list.html */}}
<main>
  <h1>{{ .Title }}</h1>

  {{ $paginator := .Paginate .Pages }}
  {{ range $paginator.Pages }}
    <article class="post-preview">
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
      <p>{{ .Summary }}</p>
    </article>
  {{ end }}

  {{ partial "pagination.html" . }}
</main>

With this template, Hugo will now render your list page with the correct subset of content and a "Next," "Previous," and page number navigation at the bottom.

Vibe Coding: Prompting for Pagination

Let's apply our "vibe coding" workflow. Instead of writing this code manually, you can ask your AI assistant to modify the existing template.

Prompt:

I have a Hugo list template at layouts/_default/list.html. It currently uses range .Pages to show all posts from a section.

Task: Modify this template to add pagination.

Instructions:

1. Use the .Paginate function on .Pages to create a paginator object. Let's show 10 items per page.
2. Update the range loop to use the paginator's pages.
3. After the loop, include Hugo's built-in pagination.html partial to render the navigation controls.

This prompt is effective because it clearly states the file, the current state, and the specific Hugo functions and partials to use.

Building Custom Pagination Controls

The built-in partial is fast, but it may not fit your site's design. For a "complex website," you'll likely want full control over the HTML and CSS of your pagination component.

To build a custom component, you'll create your own layouts/partials/pagination.html file. Inside this file, you can use various properties of the Paginator object to build your navigation.

Some of the most useful properties are:

• .HasPrev: true if there is a previous page.
• .Prev.URL: The URL of the previous page.
• .HasNext: true if there is a next page.
• .Next.URL: The URL of the next page.
• .PageNumber: The number of the current page.
• .TotalPages: The total number of pages.
• .First.URL and .Last.URL: URLs for the first and last pages.

The following resource provides a fantastic step-by-step guide to building a custom pagination partial from scratch.

By following that guide, you can create a fully custom and stylable pagination.html partial that looks something like this:

{{ $p := . }}
{{ if gt $p.TotalPages 1 }}
<nav aria-label="Page navigation">
  <ul class="pagination">
    <!-- First Page -->
    {{ if ne $p.PageNumber 1 }}
      <li class="page-item"><a class="page-link" href="{{ $p.First.URL }}">First</a></li>
    {{ end }}
    <!-- Prev Page -->
    {{ if $p.HasPrev }}
      <li class="page-item"><a class="page-link" href="{{ $p.Prev.URL }}">Previous</a></li>
    {{ end }}

    <!-- Page numbers would go here -->

    <!-- Next Page -->
    {{ if $p.HasNext }}
      <li class="page-item"><a class="page-link" href="{{ $p.Next.URL }}">Next</a></li>
    {{ end }}
    <!-- Last Page -->
    {{ if ne $p.PageNumber $p.TotalPages }}
      <li class="page-item"><a class="page-link" href="{{ $p.Last.URL }}">Last</a></li>
    {{ end }}
  </ul>
</nav>
{{ end }}

This gives you complete control over the structure and classes, allowing you to apply any CSS you wish.

Conclusion

You've now added a fundamental feature to your web development toolkit. By implementing pagination, you've made your list pages more scalable, user-friendly, and performant—all key considerations for building the complex, content-rich sites you're aiming for.

Key Takeaways:

• Pagination is enabled in hugo.toml using pagerSize and implemented in list templates.
• The .Paginate function creates a Paginator object that splits your content across multiple pages.
• You must update your range loop to iterate over $paginator.Pages.
• For quick results, {{ partial "pagination.html" . }} uses Hugo's built-in navigation.
• For full design control, you can build a custom partial using Paginator properties like .HasNext, .Next.URL, .PageNumber, and .TotalPages.

Preview of the next lesson:
Our list pages now handle large amounts of content gracefully. But what controls the order of that content? By default, Hugo sorts by weight, then date, then title. In the next lesson, we will learn how to take control of this and modify an AI-generated template to add sorting capabilities based on front matter fields.