Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Pages, Layouts and Routing

Pagination in Astro

Split long lists into pages with Astro's paginate() helper. Learn the page prop, previous and next links, page sizes, filtered lists and SEO tips.

A blog with 200 posts should not put them all on one page. Pagination splits a long list into pages of a fixed size: /blog/1, /blog/2 and so on. Astro has a built-in helper for it. You use it inside getStaticPaths, and it hands each page its slice of the data plus links to the neighbouring pages.

The paginate function

getStaticPaths receives an object with a paginate function. You call it with the full list and a page size, and it returns the path objects for you:

ASTRO
---
// src/pages/posts/[page].astro
import BaseLayout from "../../layouts/BaseLayout.astro";

export async function getStaticPaths({ paginate }) {
  const posts = [
    { title: "Post 1" }, { title: "Post 2" }, { title: "Post 3" },
    { title: "Post 4" }, { title: "Post 5" },
  ];
  return paginate(posts, { pageSize: 2 });
}

const { page } = Astro.props;
---
<BaseLayout title={`Posts, page ${page.currentPage}`}>
  <ul>
    {page.data.map((post) => <li>{post.title}</li>)}
  </ul>
  {page.url.prev && <a href={page.url.prev}>Previous</a>}
  {page.url.next && <a href={page.url.next}>Next</a>}
</BaseLayout>

With five posts and a page size of two, the build writes /posts/1, /posts/2 and /posts/3. Note that the file is named [page].astro: the parameter must be called page.

The page object

Every paginated page receives Astro.props.page:

Property Meaning
page.data The items on this page
page.start Index of the first item (0-based)
page.end Index of the last item
page.size Items per page
page.total Total number of items in the list
page.currentPage Current page number (1-based)
page.lastPage Total number of pages
page.url.current URL of this page
page.url.prev URL of the previous page, or undefined
page.url.next URL of the next page, or undefined
page.url.first / page.url.last URLs of the first and last pages (Astro 4.12 and later)

paginate() at a glance

Full list All items in one array
pageSize Slices per page
1 / 2

Page 1 at the root

Many sites want the first page at /blog rather than /blog/1. Use a rest parameter, [...page].astro in src/pages/blog/. With [...page], page one lives at /blog and page two at /blog/2:

ASTRO
---
// src/pages/blog/[...page].astro
export async function getStaticPaths({ paginate }) {
  const posts = await getAllPosts();
  return paginate(posts, { pageSize: 10 });
}
const { page } = Astro.props;
---

Filtered or grouped lists

For tags or categories, nest pagination inside another parameter. Call paginate once per group and pass params for the outer parameter:

ASTRO
---
// src/pages/tags/[tag]/[page].astro
export async function getStaticPaths({ paginate }) {
  const posts = await getAllPosts();
  const tags = [...new Set(posts.flatMap((p) => p.tags))];

  return tags.flatMap((tag) => {
    const tagged = posts.filter((p) => p.tags.includes(tag));
    return paginate(tagged, { params: { tag }, pageSize: 5 });
  });
}
const { page } = Astro.props;
const { tag } = Astro.params;
---

A pager component

Put the links in a small component so every list shares the same controls, and mark the current page for accessibility:

ASTRO
---
// src/components/Pager.astro
const { page } = Astro.props;
---
<nav aria-label="Pagination">
  {page.url.prev ? <a href={page.url.prev} rel="prev">Previous</a> : <span>Previous</span>}
  <span>Page {page.currentPage} of {page.lastPage}</span>
  {page.url.next ? <a href={page.url.next} rel="next">Next</a> : <span>Next</span>}
</nav>

SEO notes

  • Make every paginated page self-canonical (its own URL) rather than pointing to page one.
  • Keep the pager as real links so crawlers can follow them.
  • Do not hide older content behind "load more" buttons if you want it indexed.

Stand-in: our own paginate()

The helper is not magic. This stand-in builds the same page object from a list and shows what each page would receive.

Node.js Stand-in: a paginate function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: pagination with tags

Grouped pagination multiplies pages. This stand-in counts what a tag index would generate so you can plan build size.

Node.js Stand-in: pages per tag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do you call paginate()?

    getStaticPaths receives { paginate } and returns its result.
  2. 2. How is the dynamic file named for simple pagination?

    paginate() produces the params key page, so the file must use [page] or [...page].
  3. 3. What does [...page].astro change compared with [page].astro?

    With a rest parameter, the first page has no number, so /blog shows page one and /blog/2 shows page two.
  4. 4. What is page.url.prev on the first page?

    There is no previous page, so the property is undefined and you can test it before rendering a link.

Summary

  • paginate(list, { pageSize }) inside getStaticPaths creates one page per slice.
  • Each page gets Astro.props.page with data, currentPage, lastPage, total and url.prev / url.next.
  • [page].astro puts page one at /โ€ฆ/1; [...page].astro puts it at the folder root.
  • For tags, call paginate per group and pass params.
  • Keep real links in a shared pager component and make each page self-canonical.

Next: Redirects, 404 Pages and Middleware