API Reference

The Astro global is available in all contexts in .astro files. It has the following functions:

Astro.glob() is a way to load many local files into your static site setup.

---
// ./src/components/my-component.astro
const posts = await Astro.glob('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md
---

<div>
{posts.slice(0, 3).map((post) => (
  <article>
    <h1>{post.frontmatter.title}</h1>
    <p>{post.frontmatter.description}</p>
    <a href={post.frontmatter.url}>Read more</a>
  </article>
))}
</div>

.glob() only takes one parameter: a relative URL glob of which local files you’d like to import. It’s asynchronous, and returns an array of the exports from matching files.

Markdown files have the following interface:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Any data specified in this file's YAML frontmatter */
	frontmatter: T;
  /* The file path of this file */
	file: string;
  /* The rendered path of this file */
	url: string | undefined;
  /* Astro Component that renders the contents of this file */
	Content: AstroComponent;
  /* Function that returns array of h1...h6 element in this file */
	getHeaders(): Promise<{ depth: number; slug: string; text: string }[]>;
}

You can optionally provide a type for the frontmatter variable using a TypeScript generic.

---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.title}</li>)}
</ul>

Astro files have the following interface:

export interface AstroInstance {
	default: AstroComponent;
}

Other files may have various different interfaces, but Astro.glob() accepts a TypeScript generic if you know exactly what an unrecognized file type contains.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---

Astro.request is a standard Request object. It can be used to get the url, headers, method, and even body of the request. Use new URL(Astro.request.url) to get a URL object.

---
const url = new URL(Astro.request.url);
---
<h1>Origin {url.origin}</h1>

Astro.response is a standard ResponseInit object. It is used to set the status, statusText, and headers for a page’s response.

---
if(condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---

Or to set a header:

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

The canonical URL of the current page. If the site option is set, the site’s origin will be the origin of this URL.

You can also use the canonicalURL to grab the current page’s pathname.

---
const path = Astro.canonicalURL.pathname;
---

<h1>Welcome to {path}</h1>

Astro.site returns a URL made from .site in your Astro config. If undefined, this will return a URL generated from localhost.

Astro.slots contains utility functions for modifying an Astro component’s slotted children.

---
let html: string = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default')
}
---
<Fragment set:html={html} />

Astro.self allows Astro components to be recursively called. This behaviour lets you render an Astro component from within itself by using <Astro.self> in the component template. This can be helpful for iterating over large data stores and nested data-structures.

---
// NestedList.astro
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- If there is a nested data-structure we render `<Astro.self>` -->
      <!-- and can pass props through with the recursive call -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

This component could then be used like this:

---
import NestedList from './NestedList.astro';
---
<NestedList items={['A', ['B', 'C'], 'D']} />

And would render HTML like this:

<ul class="nested-list">
  <li>A</li>
  <li>
    <ul class="nested-list">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

If a page uses dynamic params in the filename, that component will need to export a getStaticPaths() function.

This function is required because Astro is a static site builder. That means that your entire site is built ahead of time. If Astro doesn’t know to generate a page at build time, your users won’t see it when they visit your site.

---
export async function getStaticPaths() {
  return [
    { params: { /* required */ }, props: { /* optional */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- Your HTML template here. -->

The getStaticPaths() function should return an array of objects to determine which paths will be pre-rendered by Astro.

The params key of every returned object tells Astro what routes to build. The returned params must map back to the dynamic parameters and rest parameters defined in your component filepath.

params are encoded into the URL, so only strings and numbers are supported as values. The value for each params object must match the parameters used in the page name.

For example, suppose that you have a page at src/pages/posts/[id].astro. If you export getStaticPaths from this page and return the following for paths:

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id:  3  } }  // Can be a number too!
  ];
}

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

Then Astro will statically generate posts/1, posts/2, and posts/3 at build time.

To pass additional data to each generated page, you can also set a props value on every returned path object. Unlike params, props are not encoded into the URL and so aren’t limited to only strings.

For example, suppose that you generate pages based off of data fetched from a remote API. You can pass the full data object to the page component inside of getStaticPaths:

---
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>

You can also pass a regular array, which may be helpful when generating or stubbing a known list of routes.

---
export async function getStaticPaths() {
  const posts = [
    {id: '1', category: "astro", title: "API Reference"},
    {id: '2', category: "react", title: "Creating a React Counter!"}
  ];
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { post }
    };
  });
}
const {id} = Astro.params;
const {post} = Astro.props;
---
<body>
  <h1>{id}: {post.title}</h1>
  <h2>Category: {post.category}</h2>
</body>

Then Astro will statically generate posts/1 and posts/2 at build time using the page component in pages/posts/[id].astro. The page can reference this data using Astro.props:

Pagination is a common use-case for websites that Astro natively supports via the paginate() function. paginate() will automatically generate the array to return from getStaticPaths() that creates one URL for every page of the paginated collection. The page number will be passed as a param, and the page data will be passed as a page prop.

export async function getStaticPaths({ paginate }) {
  // Load your data with fetch(), Astro.glob(), 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 posts
  return paginate(allPokemon, { pageSize: 10 });
}

// If set up correctly, The page prop now has everything that
// you need to render a single page (see next section).
const { page } = Astro.props;

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.

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.

RSS feeds are another common use-case that Astro supports natively. Call the rss() function to generate an /rss.xml feed for your project using the same data that you loaded for this page. This file location can be customized (see below).

// Example: /src/pages/posts/[...page].astro
// Place this function inside your Astro component script.
export async function getStaticPaths({rss}) {
  const allPosts = Astro.glob('../post/*.md');
  const sortedPosts = allPosts.sort((a, b) => Date.parse(b.date) - Date.parse(a.date));

  // Generate an RSS feed from this collection
  rss({
    // The RSS Feed title, description, and custom metadata.
    title: 'Don’s Blog',
    description: 'An example blog on Astro',
    customData: `<language>en-us</language>`,
    // The list of items for your RSS feed, sorted.
    items: sortedPosts.map(item => ({
      title: item.frontmatter.title,
      description: item.frontmatter.description,
      link: item.url,
      pubDate: item.frontmatter.fetdate,
    })),
    // Optional: Customize where the file is written to.
    // Defaults to "/rss.xml"
    dest: "/my/custom/feed.xml",
  });

  // Return a paginated collection of paths for all posts
  return [ ... ];
}

// The full type definition for the rss() function argument:
interface RSSArgument {
  /** (required) Title of the RSS Feed */
  title: string;
  /** (required) Description of the RSS Feed */
  description: string;
  /** Specify arbitrary metadata on opening <xml> tag */
  xmlns?: Record<string, string>;
  /** Specify custom data in opening of file */
  customData?: string;
  /**
   * Specify where the RSS xml file should be written.
   * Relative to final build directory. Example: '/foo/bar.xml'
   * Defaults to '/rss.xml'.
   */
  dest?: string;
  /** Return data about each item */
  items: {
    /** (required) Title of item */
    title: string;
    /** (required) Link to item */
    link: string;
    /** Publication date of item */
    pubDate?: Date;
    /** Item description */
    description?: string;
    /** Append some other XML-valid data to this item */
    customData?: string;
  }[];
}

All ESM modules include a import.meta property. Astro adds import.meta.env through Vite.

import.meta.env.SSR can be used to know when rendering on the server. Sometimes you might want different logic, for example a component that should only be rendered in the client:

import { h } from 'preact';

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <FancyComponent />;
}

Astro includes several built-in components for you to use in your projects. All built-in components are available in .astro files via import {} from 'astro/components';.

---
import { Markdown } from 'astro/components';
---
<Markdown>
  # Markdown syntax is now supported! **Yay!**
</Markdown>

See our Markdown Guide for more info.

---
import { Code } from 'astro/components';
---
<!-- Syntax highlight some JavaScript code. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Optional: customize your theme. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Optional: Enable word wrapping. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />

This component provides syntax highlighting for code blocks at build time (no client-side JavaScript included). The component is powered internally by Shiki and it supports all popular themes and languages. Plus, you can add your custom themes and languages by passing them to theme and lang respectively.

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

This component provides language-specific syntax highlighting for code blocks by applying Prism’s CSS classes. Note that you need to provide a Prism CSS stylesheet (or bring your own) for syntax highlighting to appear! See the Prism configuration section for more details.

See the list of languages supported by Prism where you can find a language’s corresponding alias. And, you can also display your Astro code blocks with lang="astro"!

---
import { Debug } from 'astro/components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

This component provides a way to inspect values on the client-side, without any JavaScript.