Skip to content

Routing Reference

There is no separate routing configuration in Astro.

Every supported page file located within the special src/pages/ directory creates a route. When the file name contains a parameter, a route can create multiple pages dynamically, otherwise it creates a single page.

By default, all Astro page routes and endpoints are generated and prerendered at build time. On-demand server rendering can be set for individual routes, or as the default.

prerender

Section titled prerender

Type: boolean
Default: true in static mode (default); false with output: 'server' configuration

Added in: astro@1.0.0

A value exported from each individual route to determine whether or not it is prerendered.

By default, all pages and endpoints are prerendered and will be statically generated at build time. You can opt out of prerendering on one or more routes, and you can have both static and on-demand rendered routes in the same project.

Per-page override

Section titled Per-page override

You can override the default value to enable on demand rendering for an individual route by exporting prerender with the value false from that file:

src/pages/rendered-on-demand.astro
---
export const prerender = false
---
<!-- server-rendered content -->
<!-- the rest of my site is static -->

Switch to server mode

Section titled Switch to server mode

You can override the default value for all routes by configuring output: 'server'. In this output mode, all pages and endpoints will be generated on the server upon request by default instead of being prerendered.

In server mode, enable prerendering for an individual route by exporting prerender with the value true from that file:

src/pages/static-about-page.astro
---
// with `output: 'server'` configured
export const prerender = true
---
<!-- My static about page -->
<!-- All other pages are rendered on demand -->

partial

Section titled partial

Type: boolean
Default: false

Added in: astro@3.4.0

A value exported from an individual route to determine whether or not it should be rendered as a full HTML page.

By default, all files located within the reserved src/pages/ directory automatically include the <!DOCTYPE html> declaration and additional <head> content such as Astro’s scoped styles and scripts.

You can override the default value to designate the content as a page partial for an individual route by exporting a value for partial from that file:

src/pages/my-page-partial.astro
---
export const partial = true
---
<!-- Generated HTML available at a URL -->
<!-- Available to a rendering library -->

The export const partial must be identifiable statically. It can have the value of:

  • The boolean true.
  • An environment variable using import.meta.env such as import.meta.env.USE_PARTIALS.

getStaticPaths()

Section titled getStaticPaths()

Type: (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

Added in: astro@1.0.0

A function to generate multiple, prerendered page routes from a single .astro page component with one or more parameters in its file path. Use this for routes that will be created at build time, also known as static site building.

The getStaticPaths() function must return an array of objects to determine which URL paths will be prerendered by Astro. Each object must include a params object, to specify route paths. The object may optionally contain a props object with data to be passed to each page template.

src/pages/blog/[post].astro
---
// In 'server' mode, opt in to prerendering:
// export const prerender = true


export async function getStaticPaths() {
  return [
    // { params: { /* required */ }, props: { /* optional */ } },
    { params: { post: '1' } }, // [post] is the parameter
    { params: { post: '2' } }, // must match the file name
    // ...
  ];
}
---
<!-- Your HTML template here. -->

getStaticPaths() can also be used in static file endpoints for dynamic routing.

params

Section titled params

The params key of each object in the array returned by getStaticPaths() tells Astro what routes to build.

The keys in params must match the parameters defined in your component file path. The value for each params object must match the parameters used in the page name. params are encoded into the URL, so only strings are supported as values.

For example,src/pages/posts/[id].astrohas an id parameter in its file name. The following getStaticPaths() function in this .astro component tells Astro to statically generate posts/1, posts/2, and posts/3 at build time.

src/pages/posts/[id].astro
---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}


const { id } = Astro.params;
---
<h1>{id}</h1>

Data passing with props

Section titled Data passing with props

To pass additional data to each generated page, you can set a props value on each object in the array returned by getStaticPaths(). Unlike params, props are not encoded into the URL and so aren’t limited to only strings.

For example, if you generate pages with data fetched from a remote API, you can pass the full data object to the page component inside of getStaticPaths(). The page template can reference the data from each post using Astro.props.

src/pages/posts/[id].astro
---
export async function getStaticPaths() {
  const data = await fetch('...').then(response => response.json());


  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}


const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>

paginate()

Section titled paginate()

Added in: astro@1.0.0

A function that can be returned from getStaticPaths() to divide a collection of content items into separate pages.

paginate() will automatically generate the necessary array to return from getStaticPaths() to create one URL for every page of your paginated collection. The page number will be passed as a param, and the page data will be passed as a page prop.

The following example fetches and passes 150 items to the paginate function, and creates static, prerendered pages at build time that will display 10 items per page:

src/pages/pokemon/[page].astro
export async function getStaticPaths({ paginate }) {
  // Load your data with fetch(), getCollection(), etc.
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;


  // Return a paginated collection of paths for all items
  return paginate(allPokemon, { pageSize: 10 });
}


const { page } = Astro.props;

paginate() has the following arguments:

  • data - array containing the page’s data passed to the paginate() function
  • options - Optional object with the following properties:
    • pageSize - The number of items shown per page (10 by default)
    • params - Send additional parameters for creating dynamic routes
    • props - Send additional props to be available on each page

paginate() assumes a file name of [page].astro or [...page].astro. The page param becomes the page number in your URL:

  • /posts/[page].astro would generate the URLs /posts/1, /posts/2, /posts/3, etc.
  • /posts/[...page].astro would generate the URLs /posts, /posts/2, /posts/3, etc.

The pagination page prop

Section titled The pagination page prop

Type: Page<TData>

Pagination will pass a page prop to every rendered page that represents a single page of data in the paginated collection. This includes the data that you’ve paginated (page.data) as well as metadata for the page (page.url, page.start, page.end, page.total, etc). This metadata is useful for things like a “Next Page” button or a “Showing 1-10 of 100” message.

page.data
Section titled page.data

Type: Array<TData>

Array of data returned from the paginate() function for the current page.

page.start
Section titled page.start

Type: number

Index of the first item on the current page, starting at 0. (e.g. if pageSize: 25, this would be 0 on page 1, 25 on page 2, etc.)

page.end
Section titled page.end

Type: number

Index of the last item on the current page.

page.size
Section titled page.size

Type: number
Default: 10

The total number of items per page.

page.total
Section titled page.total

Type: number

The total number of items across all pages.

page.currentPage
Section titled page.currentPage

Type: number

The current page number, starting with 1.

page.lastPage
Section titled page.lastPage

Type: number

The total number of pages.

page.url.current
Section titled page.url.current

Type: string

Get the URL of the current page (useful for canonical URLs). If a value is set for base, the URL starts with that value.

page.url.prev
Section titled page.url.prev

Type: string | undefined

Get the URL of the previous page (will be undefined if on the first page). If a value is set for base, the URL starts with that value.

page.url.next
Section titled page.url.next

Type: string | undefined

Get the URL of the next page (will be undefined if on the last page). If a value is set for base, the URL starts with that value.

page.url.first
Section titled page.url.first

Type: string

Get the URL of the first page (will be undefined if on the first page). If a value is set for base, the URL starts with that value.

page.url.last
Section titled page.url.last

Type: string

Get the URL of the last page (will be undefined if on the last page). If a value is set for base, the URL starts with that value.

page.url.first
Section titled page.url.first

Type: string | undefined

Added in: astro@4.12.0

Get the URL of the first page (will be undefined if on page 1). If a value is set for base, prepend the base path to the URL.

page.url.last
Section titled page.url.last

Type: string | undefined

Added in: astro@4.12.0

Get the URL of the last page (will be undefined if no more pages). If a value is set for base, prepend the base path to the URL.

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community