Astro uses file-based routing to generate your build URLs based on the file layout of your project
Navigating between pagesSection titled Navigating between pages
Astro uses standard HTML
<a> elements to navigate between routes. There is no framework-specific
<Link> component provided.
Static routesSection titled Static routes
.astro page components as well as Markdown and MDX Files (
.mdx) within the
src/pages/ directory automatically become pages on your website. Each page’s route corresponds to its path and filename within the
Dynamic routesSection titled 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) ModeSection titled 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
This will generate three pages:
/dogs/spot, each displaying the corresponding dog name.
The filename can include multiple parameters, which must all be included in the
params objects in
This will generate
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
📚 Learn more about
Rest parametersSection titled 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:
This will generate
/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:
In this example, a request for
/withastro/astro/tree/main/docs/public/favicon.svg would be split into the following named parameters:
Example: Dynamic pages at multiple levelsSection titled 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.
Server (SSR) ModeSection titled Server (SSR) Mode
In SSR mode, dynamic routes are defined the same way: include
[...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.
This page will be served for any value of
Modifying the Section titled Modifying the [...slug] example for SSR
[...slug] 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.
RedirectsSection titled 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.
Configured RedirectsSection titled Configured Redirects
You can specify a mapping of permanent redirects in your Astro config with the
redirects value. For most redirects, this is a mapping of an old route to the new route:
These redirects follow the same rules as file-based routes. Dynamic routes are allowed as long as both the new and old routes contain the same parameters, for example:
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
astro build, Astro will output HTML files with the meta refresh tag by default. Supported adapters will instead write out the host’s configuration file with the redirects.
The status code is
301 by default. If building to HTML files the status code is not used by the server.
Dynamic redirectsSection titled Dynamic redirects
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.
Route Priority OrderSection titled Route Priority Order
It’s possible for multiple routes to match the same URL path. For example each of these routes would match
Astro needs to know which route should be used to build the page. To do so, it sorts them according to the following rules:
- Static routes without path parameters will take precedence over all other routes
- Dynamic routes using named parameters take precedence over rest parameters
- Pre-rendered dynamic routes take precedence over server dynamic routes
- Rest parameters have the lowest priority
- Endpoints always take precedence over pages
- Ties are resolved alphabetically
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
pages/posts/[pid].astro- Will build
/posts/abc, etc. But not
pages/posts/[...slug].astro- Will build
/posts/a/b/c, etc. But not
Redirects also follow the same rules, but are prioritized last; if there is a file-based route and a redirect with the same route priority level, the file-based route is chosen.
PaginationSection titled 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/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:
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 Section titled 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, but here are the highlights:
- page.data - array containing the page’s slice of data that you passed to the
- page.url.next - link to the next page in the set
- page.url.prev - link to the previous page in the set
Complete API referenceSection titled Complete API reference
Nested PaginationSection titled Nested Pagination
A more advanced use-case for pagination is nested pagination. This is when pagination is combined with other dynamic route params. You can use nested pagination to group your paginated collection by some property or tag.
For example, if you want to group your paginated Markdown posts by some tag, you would use nested pagination by creating a
/src/pages/[tag]/[page].astro page that would match the following URLS:
Nested pagination works by returning an array of
paginate() results from
getStaticPaths(), one for each grouping.
In the following example, we will implement nested pagination to build the URLs listed above:
Excluding pagesSection titled Excluding pages
You can exclude pages or directories 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
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/posts/post1.md will be built as page routes and HTML files.