Routing

Astro uses file-based routing to generate your build URLs based on the file layout of your project src/pages/ directory.

Navigating Between Pages

Astro uses standard HTML <a> elements to navigate between routes. There is no framework-specific <Link> component provided.

src/pages/index.astro

<p>Read more <a href="/about/">about</a> Astro!</p>

<!-- With `base: "/docs"` configured -->
<p>Learn more in our <a href="/docs/reference/">reference</a> section!</p>

Static Routes

.astro page components as well as Markdown and MDX Files (.md, .mdx) within the src/pages/ directory automatically become pages on your website. Each page’s route corresponds to its path and filename within the src/pages/ directory.

# Example: Static routes
src/pages/index.astro        -> mysite.com/
src/pages/about.astro        -> mysite.com/about
src/pages/about/index.astro  -> mysite.com/about
src/pages/about/me.astro     -> mysite.com/about/me
src/pages/posts/1.md         -> mysite.com/posts/1

There is no separate “routing config” to maintain in an Astro project! When you add a file to the src/pages/ directory, a new route is automatically created for you. In static builds, you can customize the file output format using the build.format configuration option.

Dynamic Routes

An Astro page file can specify dynamic route parameters in its filename to generate multiple, matching pages. For example, src/pages/authors/[author].astro generates a bio page for every author on your blog. author becomes a parameter that you can access from inside the page. In Astro’s default static output mode, these pages are generated at build time, and so you must predetermine the list of authors that get a corresponding file. In SSR mode, a page will be generated on request for any route that matches.

Static (SSG) Mode

Because all routes must be determined at build time, a dynamic route must export a getStaticPaths() that returns an array of objects with a params property. Each of these objects will generate a corresponding route. [dog].astro defines the dynamic dog parameter in its filename, so the objects returned by getStaticPaths() must include dog in their params. The page can then access this parameter using Astro.params.

src/pages/dogs/[dog].astro

---
export function getStaticPaths() {
  return [
    { params: { dog: "clifford" }},
    { params: { dog: "rover" }},
    { params: { dog: "spot" }},
  ];
}

const { dog } = Astro.params;
---
<div>Good dog, {dog}!</div>

This will generate three pages: /dogs/clifford, /dogs/rover, and /dogs/spot, each displaying the corresponding dog name. The filename can include multiple parameters, which must all be included in the params objects in getStaticPaths():

src/pages/[lang]-[version]/info.astro

---
export function getStaticPaths() {
  return [
    { params: { lang: "en", version: "v1" }},
    { params: { lang: "fr", version: "v2" }},
  ];
}

const { lang, version } = Astro.params;
---

This will generate /en-v1/info and /fr-v2/info. Parameters can be included in separate parts of the path. For example, the file src/pages/[lang]/[version]/info.astro with the same getStaticPaths() above will generate the routes /en/v1/info and /fr/v2/info.

Rest Parameters

If you need more flexibility in your URL routing, you can use a rest parameter ([...path]) in your .astro filename to match file paths of any depth:

src/pages/sequences/[...path].astro

---
export function getStaticPaths() {
  return [
    { params: { path: "one/two/three" }},
    { params: { path: "four" }},
    { params: { path: undefined }}
  ]
}

const { path } = Astro.params;
---

This will generate /sequences/one/two/three, /sequences/four, and /sequences. (Setting the rest parameter to undefined allows it to match the top level page.) Rest parameters can be used with other named parameters. For example, GitHub’s file viewer can be represented with the following dynamic route:

/[org]/[repo]/tree/[branch]/[...file]

In this example, a request for /withastro/astro/tree/main/docs/public/favicon.svg would be split into the following named parameters:

{
  org: "withastro",
  repo: "astro",
  branch: "main",
  file: "docs/public/favicon.svg"
}

Example: Dynamic Pages at Multiple Levels

In the following example, a rest parameter ([...slug]) and the props feature of getStaticPaths() generate pages for slugs of different depths.

src/pages/[...slug].astro

---
export function getStaticPaths() {
  const pages = [
    {
      slug: undefined,
      title: "Astro Store",
      text: "Welcome to the Astro store!",
    },
    {
      slug: "products",
      title: "Astro products",
      text: "We have lots of products for you",
    },
    {
      slug: "products/astro-handbook",
      title: "The ultimate Astro handbook",
      text: "If you want to learn Astro, you must read this book.",
    },
  ];
  
  return pages.map(({ slug, title, text }) => {
    return {
      params: { slug },
      props: { title, text },
    };
  });
}

const { title, text } = Astro.props;
---
<html>
  <head>
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>{text}</p>
  </body>
</html>

On-demand Dynamic Routes

For on-demand rendering with an adapter, dynamic routes are defined the same way: include [param] or [...path] brackets in your file names to match arbitrary strings or paths. But because the routes are no longer built ahead of time, the page will be served to any matching route. Since these are not “static” routes, getStaticPaths should not be used.

src/pages/resources/[resource]/[id].astro

---
export const prerender = false; // Not needed in 'server' mode
const { resource, id } = Astro.params;
---
<h1>{resource}: {id}</h1>

This page will be served for any value of resource and id: resources/users/1, resources/colors/blue, etc.

Modifying the Example for SSR

Because SSR pages can’t use getStaticPaths(), they can’t receive props. The previous example can be adapted for SSR mode by looking up the value of the slug param in an object. If the route is at the root (”/”), the slug param will be undefined. If the value doesn’t exist in the object, we redirect to a 404 page.

src/pages/[...slug].astro

---
const pages = [
  {
    slug: undefined,
    title: 'Astro Store',
    text: 'Welcome to the Astro store!',
  },
  {
    slug: 'products',
    title: 'Astro products',
    text: 'We have lots of products for you',
  },
  {
    slug: 'products/astro-handbook',
    title: 'The ultimate Astro handbook',
    text: 'If you want to learn Astro, you must read this book.',
  }
];

const { slug } = Astro.params;
const page = pages.find((page) => page.slug === slug);
if (!page) return Astro.redirect("/404");
const { title, text } = page;
---
<html>
  <head>
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>{text}</p>
  </body>
</html>

Redirects

Sometimes you will need to redirect your readers to a new page, either permanently because your site structure has changed or in response to an action such as logging in to an authenticated route. You can define rules to redirect users to permanently-moved pages in your Astro config. Or, redirect users dynamically as they use your site.

Configured Redirects

You can specify a mapping of permanent redirects in your Astro config with the redirects value. For internal redirects, this is a mapping of an old route path to the new route. As of Astro v5.2.0, it is also possible to redirect to external URLs:

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  redirects: {
    "/old-page": "/new-page",
    "/blog": "https://example.com/blog"
  }
});

These redirects follow the same priority rules as file-based routes and will always take lower precedence than an existing page file of the same name in your project. Dynamic routes are allowed as long as both the new and old routes contain the same parameters, for example:

{
  "/blog/[...slug]": "/articles/[...slug]"
}

Using SSR or a static adapter, you can also provide an object as the value, allowing you to specify the status code in addition to the new destination:

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  redirects: {
    "/old-page": {
      status: 302,
      destination: "/new-page"
    },
    "/news": {
      status: 302,
      destination: "https://example.com/news"
    }
  }
});

Dynamic Redirects

On the Astro global, the Astro.redirect method allows you to redirect to another page dynamically. You might do this after checking if the user is logged in by getting their session from a cookie.

src/pages/account.astro

---
import { isLoggedIn } from "../utils";

const cookie = Astro.request.headers.get("cookie");

// If the user is not logged in, redirect them to the login page
if (!isLoggedIn(cookie)) {
  return Astro.redirect("/login");
}
---

Rewrites

A rewrite allows you to serve a different route without redirecting the browser to a different page. The browser will show the original address in the URL bar, but will instead display the content of the URL provided to Astro.rewrite().

For content that has permanently moved, or to direct your user to a different page with a new URL (e.g. a user dashboard after logging in), use a redirect instead.

Rewrites can be useful for showing the same content at multiple paths (e.g. /products/shoes/men/ and /products/men/shoes/) without needing to maintain two different source files. Rewrites are also useful for SEO purposes and user experience. They allow you to display content that otherwise would require redirecting your visitor to a different page or would return a 404 status. One common use of rewrites is to show the same localized content for different variants of a language. The following example uses a rewrite to render the /es/ version of a page when the /es-CU/ (Cuban Spanish) URL path is visited. When a visitor navigates to the URL /es-cu/articles/introduction, Astro will render the content generated by the file src/pages/es/articles/introduction.astro.

src/pages/es-cu/articles/introduction.astro

---
return Astro.rewrite("/es/articles/introduction");
---

Use context.rewrite() in your endpoint files to reroute to a different page:

src/pages/api.js

export function GET(context) {
  if (!context.locals.allowed) {
    return context.rewrite("/");
  }
}

Route Priority Order

It’s possible for multiple defined routes to attempt to build the same URL path. For example, all of these routes could build /posts/create:

src/pages/
  [...slug].astro
  posts/
    create.astro
    [page].astro
    [pid].ts
    [...slug].astro

Astro needs to know which route should be used to build the page. To do so, it sorts them according to the following rules in order:

Routes with more path segments will take precedence over less specific routes. In the example above, all routes under /posts/ take precedence over /[...slug].astro at the root
Static routes without path parameters will take precedence over dynamic routes. E.g. /posts/create.astro takes precedence over all the other routes in the example
Dynamic routes using named parameters take precedence over rest parameters. E.g. /posts/[page].astro takes precedence over /posts/[...slug].astro
Pre-rendered dynamic routes take precedence over server dynamic routes
Endpoints take precedence over pages
File-based routes take precedence over redirects
If none of the rules above decide the order, routes are sorted alphabetically based on the default locale of your Node installation

Given the example above, here are a few examples of how the rules will match a requested URL to the route used to build the HTML:

pages/posts/create.astro - Will build only /posts/create
pages/posts/[pid].ts - Will build /posts/abc, /posts/xyz, etc. But not /posts/create
pages/posts/[page].astro - Will build /posts/1, /posts/2, etc. But not /posts/create, /posts/abc nor /posts/xyz
pages/posts/[...slug].astro - Will build /posts/1/2, /posts/a/b/c, etc. But not /posts/create, /posts/1, /posts/abc, etc.
pages/[...slug].astro - Will build /abc, /xyz, /abc/xyz, etc. But not /posts/create, /posts/1, /posts/abc, etc.

Pagination

Astro supports built-in pagination for large collections of data that need to be split into multiple pages. Astro will generate common pagination properties, including previous/next page URLs, total number of pages, and more. Paginated route names should use the same [bracket] syntax as a standard dynamic route. For instance, the file name /astronauts/[page].astro will generate routes for /astronauts/1, /astronauts/2, etc, where [page] is the generated page number. You can use the paginate() function to generate these pages for an array of values like so:

src/pages/astronauts/[page].astro

---
export function getStaticPaths({ paginate }) {
  const astronautPages = [
    { astronaut: "Neil Armstrong" },
    { astronaut: "Buzz Aldrin" },
    { astronaut: "Sally Ride" },
    { astronaut: "John Glenn" },
  ];
  
  // Generate pages from our array of astronauts, with 2 to a page
  return paginate(astronautPages, { pageSize: 2 });
}
// All paginated data is passed on the "page" prop
const { page } = Astro.props;
---
<!-- Display the current page number. `Astro.params.page` can also be used! -->
<h1>Page {page.currentPage}</h1>
<ul>
  <!-- List the array of astronaut info -->
  {page.data.map(({ astronaut }) => <li>{astronaut}</li>)}
</ul>

This generates the following pages, with 2 items to a page:

/astronauts/1 - Page 1: Displays “Neil Armstrong” and “Buzz Aldrin”
/astronauts/2 - Page 2: Displays “Sally Ride” and “John Glenn”

The `page` Prop

When you use the paginate() function, each page will be passed its data via a page prop. The page prop has many useful properties:

data - Array containing the page’s slice of data that you passed to the paginate() function
start - The count of the first item on the page, starting from 0
end - The count of the last item on the page, starting from 0
total - Total number of results
currentPage - The current page number, starting from 1
size - Number of items per page (default: 10)
lastPage - Number of last page
url.current - URL of the current page
url.prev - URL of the previous page (if there is one)
url.next - URL of the next page (if there is one)
url.first - URL of the first page (if the current page is not the first page)
url.last - URL of the last page (if the current page in not the last page)

Excluding Pages

You can exclude pages or directories within src/pages from being built by prefixing their names with an underscore (_). Files with the _ prefix won’t be recognized by the router and won’t be placed into the dist/ directory. You can use this to temporarily disable pages, and also to put tests, utilities, and components in the same folder as their related pages. In this example, only src/pages/index.astro and src/pages/projects/project1.md will be built as page routes and HTML files.

src/pages/
  _hidden-directory/
    page1.md
    page2.md
  _hidden-page.astro
  index.astro
  projects/
    _SomeComponent.astro
    _utils.js
    project1.md

Getting Started

Core Concepts

Guides

Integrations

Navigating Between Pages

Static Routes

Dynamic Routes

Static (SSG) Mode

Rest Parameters

Example: Dynamic Pages at Multiple Levels

On-demand Dynamic Routes

Modifying the Example for SSR

Redirects

Configured Redirects

Dynamic Redirects

Rewrites

Route Priority Order

The `page` Prop

Excluding Pages

Getting Started

Core Concepts

Guides

Integrations

​Navigating Between Pages

​Static Routes

​Dynamic Routes

​Static (SSG) Mode

​Rest Parameters

​Example: Dynamic Pages at Multiple Levels

​On-demand Dynamic Routes

​Modifying the Example for SSR

​Redirects

​Configured Redirects

​Dynamic Redirects

​Rewrites

​Route Priority Order

​Pagination

​The page Prop

​Excluding Pages

Navigating Between Pages

Static Routes

Dynamic Routes

Static (SSG) Mode

Rest Parameters

Example: Dynamic Pages at Multiple Levels

On-demand Dynamic Routes

Modifying the Example for SSR

Redirects

Configured Redirects

Dynamic Redirects

Rewrites

Route Priority Order

Pagination

The `page` Prop

Excluding Pages