API Reference

هذا المحتوى غير متوفر بلغتك بعد.

`Astro` global

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

`Astro.glob()`

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

---
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>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.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.

.glob() can’t take variables or strings that interpolate them, as they aren’t statically analyzable. (See the troubleshooting guide for a workaround.) This is because Astro.glob() is a wrapper of Vite’s import.meta.glob().

You can also use import.meta.glob() itself in your Astro project. You may want to do this when:

You need this feature in a file that isn’t .astro, like an API route. Astro.glob() is only available in .astro files, while import.meta.glob() is available anywhere in the project.
You don’t want to load each file immediately. import.meta.glob() can return functions that import the file content, rather than returning the content itself. Note that this import includes all styles and scripts for any imported files. These will be bundled and added to the page whether or not a file is actually used, as this is decided by static analysis, not at runtime.
You want access to each file’s path. import.meta.glob() returns a map of a file’s path to its content, while Astro.glob() returns a list of content.
You want to pass multiple patterns; for example, you want to add a “negative pattern” that filters out certain files. import.meta.glob() can optionally take an array of glob strings, rather than a single string.

Markdown Files

Markdown files loaded with Astro.glob() return the following MarkdownInstance interface:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Any data specified in this file's YAML frontmatter */
  frontmatter: T;
  /* The absolute 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: AstroComponentFactory;
  /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML frontmatter */
  rawContent(): string;
  /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */
  compiledContent(): string;
  /* Function that returns an array of the h1...h6 elements in this file */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

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.frontmatter.title}</li>)}
</ul>

Astro Files

Astro files have the following interface:

export interface AstroInstance {
  /* The file path of this file */
  file: string;
  /* The URL for this file (if it is in the pages directory) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Other Files

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.props`

Astro.props is an object containing any values that have been passed as component attributes. Layout components for .md and .mdx files receive frontmatter values as props.

---
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>

---
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />

Learn more about how Markdown and MDX Layouts handle props.

Learn how to add TypeScript type definitions for your props.

`Astro.params`

Astro.params is an object containing the values of dynamic route segments matched for this request.

In static builds, this will be the params returned by getStaticPaths() used for prerendering dynamic routes.

In SSR builds, this can be any value matching the path segments in the dynamic route pattern.

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

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

`Astro.request`

Type: Request

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

<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
<p>Received request headers: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

`Astro.response`

Type: ResponseInit & { readonly headers: Headers }

Astro.response is a standard ResponseInit object. It has the following structure.

status: The numeric status code of the response, e.g., 200.
statusText: The status message associated with the status code, e.g., 'OK'.
headers: A Headers instance that you can use to set the HTTP headers of the response.

Astro.response 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=/;');
---

`Astro.cookies`

Type: AstroCookies

أُضيفت في: astro@1.4.0

Astro.cookies contains utilities for reading and manipulating cookies in server-side rendering mode.

`get`

Type: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

Gets the cookie as an AstroCookie object, which contains the value and utility functions for converting the cookie to non-string types.

`has`

Type: (key: string, options?: AstroCookieGetOptions) => boolean

Whether this cookie exists. If the cookie has been set via Astro.cookies.set() this will return true, otherwise it will check cookies in the Astro.request.

`set`

Type: (key: string, value: string | object, options?: AstroCookieSetOptions) => void

Sets the cookie key to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set cookie features, such as the maxAge or httpOnly.

`delete`

Type: (key: string, options?: AstroCookieDeleteOptions) => void

Invalidates a cookie by setting the expiration date in the past (0 in Unix time).

Once a cookie is “deleted” (expired), Astro.cookies.has() will return false and Astro.cookies.get() will return an AstroCookie with a value of undefined. Options available when deleting a cookie are: domain, path, httpOnly, sameSite, and secure.

`merge`

Type: (cookies: AstroCookies) => void

Merges a new AstroCookies instance into the current instance. Any new cookies will be added to the current instance and any cookies with the same name will overwrite existing values.

`headers`

Type: () => Iterator<string>

Gets the header values for Set-Cookie that will be sent out with the response.

`AstroCookie`

Getting a cookie via Astro.cookies.get() returns a AstroCookie type. It has the following structure.

`value`

Type: string

The raw string value of the cookie.

`json`

Type: () => Record<string, any>

Parses the cookie value via JSON.parse(), returning an object. Throws if the cookie value is not valid JSON.

`number`

Type: () => number

Parses the cookie value as a Number. Returns NaN if not a valid number.

`boolean`

Type: () => boolean

Converts the cookie value to a boolean.

`AstroCookieGetOptions`

أُضيفت في: astro@4.1.0

Getting a cookie also allows specifying options via the AstroCookieGetOptions interface:

`decode`

Type: (value: string) => string

Allows customization of how a cookie is deserialized into a value.

`AstroCookieSetOptions`

أُضيفت في: astro@4.1.0

Setting a cookie via Astro.cookies.set() allows passing in a AstroCookieSetOptions to customize how the cookie is serialized.

`domain`

Type: string

Specifies the domain. If no domain is set, most clients will interpret to apply to the current domain.

`expires`

Type: Date

Specifies the date on which the cookie will expire.

`httpOnly`

Type: boolean

If true, the cookie will not be accessible client-side.

`maxAge`

Type: number

Specifies a number, in seconds, for which the cookie is valid.

`path`

Type: string

Specifies a subpath of the domain in which the cookie is applied.

`sameSite`

Type: boolean | 'lax' | 'none' | 'strict'

Specifies the value of the SameSite cookie header.

`secure`

Type: boolean

If true, the cookie is only set on https sites.

`encode`

Type: (value: string) => string

Allows customizing how the cookie is serialized.

`Astro.redirect()`

Type: (path: string, status?: number) => Response

Allows you to redirect to another page, and optionally provide an HTTP response status code as a second parameter.

A page (and not a child component) must return the result of Astro.redirect() for the redirect to occur.

For statically-generated sites, this will produce a client redirect using a <meta http-equiv="refresh"> tag and does not support status codes.

When using an on-demand rendering mode, status codes are supported. Astro will serve redirected requests with a default HTTP response status of 302 unless another code is specified.

The following example redirects a user to a login page:

---
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');
}
---

`Astro.rewrite()`

Type: (rewritePayload: string | URL | Request) => Promise<Response>

أُضيفت في: astro@4.13.0

Allows you to serve content from a different URL or path without redirecting the browser to a new page.

The method accepts either a string, a URL, or a Request for the location of the path.

Use a string to provide an explicit path:

---
return Astro.rewrite("/login")
---

Use a URL type when you need to construct the URL path for the rewrite. The following example renders a page’s parent path by creating a new URL from the relative "../" path:

---
return Astro.rewrite(new URL("../", Astro.url))
---

Use a Request type for complete control of the Request sent to the server for the new path. The following example sends a request to render the parent page while also providing headers:

---
return Astro.rewrite(new Request(new URL("../", Astro.url), {
  headers: {
    "x-custom-header": JSON.stringify(Astro.locals.someValue)
  }
}))
---

`Astro.url`

Type: URL

أُضيفت في: astro@1.0.0-rc

A URL object constructed from the current Astro.request.url URL string value. Useful for interacting with individual properties of the request URL, like pathname and origin.

Equivalent to doing new URL(Astro.request.url).

Astro.url will be localhost in dev mode if site is not configured for static sites, and for on-demand rendered sites using server or hybrid output.

<h1>The current URL is: {Astro.url}</h1>
<h1>The current URL pathname is: {Astro.url.pathname}</h1>
<h1>The current URL origin is: {Astro.url.origin}</h1>

You can also use Astro.url to create new URLs by passing it as an argument to new URL().

---
// Example: Construct a canonical URL using your production domain
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Example: Construct a URL for SEO meta tags using your current domain
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`Astro.clientAddress`

Type: string

أُضيفت في: astro@1.0.0-rc

Specifies the IP address of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

---
const ip = Astro.clientAddress;
---

<div>Your IP address is: <span class="address">{ ip }</span></div>

`Astro.site`

Type: URL | undefined

Astro.site returns a URL made from site in your Astro config. If site in your Astro config isn’t defined, Astro.site won’t be defined.

`Astro.generator`

Type: string

أُضيفت في: astro@1.0.0

Astro.generator is a convenient way to add a <meta name="generator"> tag with your current version of Astro. It follows the format "Astro v1.x.x".

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Built with <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

`Astro.slots`

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

`Astro.slots.has()`

Type: (slotName: string) => boolean

You can check whether content for a specific slot name exists with Astro.slots.has(). This can be useful when you want to wrap slot contents, but only want to render the wrapper elements when the slot is being used.

---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>More</h2>
    <slot name="more" />
  </aside>
)}

`Astro.slots.render()`

Type: (slotName: string, args?: any[]) => Promise<string>

You can asynchronously render the contents of a slot to a string of HTML using Astro.slots.render().

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

Astro.slots.render() optionally accepts a second argument: an array of parameters that will be forwarded to any function children. This can be useful for custom utility components.

For example, this <Shout /> component converts its message prop to uppercase and passes it to the default slot:

---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />

A callback function passed as <Shout />’s child will receive the all-caps message parameter:

---
import Shout from "../components/Shout.astro";
---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- renders as <div>SLOTS!</div> -->

Callback functions can be passed to named slots inside a wrapping HTML element tag with a slot attribute. This element is only used to transfer the callback to a named slot and will not be rendered onto the page.

<Shout message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Shout>

Use a standard HTML element for the wrapping tag, or any lower case tag (e.g. <fragment> instead of <Fragment />) that will not be interpreted as a component. Do not use the HTML <slot> element as this will be interpreted as an Astro slot.

`Astro.self`

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.

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

`Astro.locals`

أُضيفت في: astro@2.4.0

Astro.locals is an object containing any values from the context.locals object from a middleware. Use this to access data returned by middleware in your .astro files.

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<ul>
    {orders.map(order => {
        return <li>{/* do something with each order */}</li>
    })}
</ul>

`Astro.preferredLocale`

Type: string | undefined

أُضيفت في: astro@3.5.0

Astro.preferredLocale is a computed value that represents the preferred locale of the user.

It is computed by checking the configured locales in your i18n.locales array and locales supported by the users’s browser via the header Accept-Language. This value is undefined if no such match exists.

This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

`Astro.preferredLocaleList`

Type: string[] | undefined

أُضيفت في: astro@3.5.0

Astro.preferredLocaleList represents the array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor.

If none of the browser’s requested languages are found in your locales array, then the value is []: you do not support any of your visitor’s preferred locales.

If the browser does not specify any preferred languages, then this value will be i18n.locales: all of your supported locales will be considered equally preferred by a visitor with no preferences.

This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

`Astro.currentLocale`

Type: string | undefined

أُضيفت في: astro@3.5.6

The locale computed from the current URL, using the syntax specified in your locales configuration. If the URL does not contain a /[locale]/ prefix, then the value will default to i18n.defaultLocale.

`Astro.getActionResult()`

Type: (action: TAction) => ActionReturnType<TAction> | undefined

أُضيفت في: astro@4.15.0 تجريبي

Astro.getActionResult() is a function that returns the result of an Action submission. This accepts an action function as an argument (e.g. actions.logout), and returns a data or error object when a submission is received. Otherwise, it will return undefined.

---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.logout);
---

<form action={actions.logout}>
  <button type="submit">Log out</button>
</form>
{result?.error && <p>Failed to log out. Please try again.</p>}

`Astro.callAction()`

أُضيفت في: astro@4.15.0 تجريبي

Astro.callAction() is a function used to call an Action handler directly from your Astro component. This function accepts an Action function as the first argument (e.g. actions.logout) and any input that action receives as the second argument. It returns the result of the action as a promise.

---
import { actions } from 'astro:actions';

const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

Endpoint Context

Endpoint functions receive a context object as the first parameter. It mirrors many of the Astro global properties.

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`context.params`

context.params is an object containing the values of dynamic route segments matched for this request.

In static builds, this will be the params returned by getStaticPaths() used for prerendering dynamic routes.

In SSR builds, this can be any value matching the path segments in the dynamic route pattern.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

export function GET({ params }: APIContext) {
  return new Response(
    JSON.stringify({ id: params.id }),
  );
}

`context.props`

أُضيفت في: astro@1.5.0

context.props is an object containing any props passed from getStaticPaths(). Because getStaticPaths() is not used when building for SSR (server-side rendering), context.props is only available in static builds.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' }, props: { author: 'Blu' } },
    { params: { id: '2' }, props: { author: 'Erika' } },
    { params: { id: '3' }, props: { author: 'Matthew' } }
  ];
}

export function GET({ props }: APIContext) {
  return new Response(
    JSON.stringify({ author: props.author }),
  );
}

`context.request`

Type: Request

A standard Request object. It can be used to get the url, headers, method, and even body of the request.

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Hello ${request.url}`);
}

`context.cookies`

Type: AstroCookies

context.cookies contains utilities for reading and manipulating cookies.

`context.url`

Type: URL

أُضيفت في: astro@1.5.0

A URL object constructed from the current context.request.url URL string value.

`context.clientAddress`

Type: string

أُضيفت في: astro@1.5.0

Specifies the IP address of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Your IP address is: ${clientAddress}`);
}

`context.site`

Type: URL | undefined

أُضيفت في: astro@1.5.0

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

`context.generator`

Type: string

أُضيفت في: astro@1.5.0

context.generator is a convenient way to indicate the version of Astro your project is running. It follows the format "Astro v1.x.x".

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

`context.redirect()`

Type: (path: string, status?: number) => Response

أُضيفت في: astro@1.5.0

context.redirect() returns a Response object that allows you to redirect to another page. This function is only available when building for SSR (server-side rendering) and should not be used for static sites.

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

`context.rewrite()`

Type: (rewritePayload: string | URL | Request) => Promise<Response>

أُضيفت في: astro@4.13.0

Allows you to serve content from a different URL or path without redirecting the browser to a new page.

The method accepts either a string, a URL, or a Request for the location of the path.

Use a string to provide an explicit path:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite('/login');
}

Use a URL type when you need to construct the URL path for the rewrite. The following example renders a page’s parent path by creating a new URL from the relative "../" path:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new URL("../", Astro.url));
}

Use a Request type for complete control of the Request sent to the server for the new path. The following example sends a request to render the parent page while also providing headers:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new Request(new URL("../", Astro.url), {
   headers: {
     "x-custom-header": JSON.stringify(Astro.locals.someValue)
   }
 }));
}

`context.locals`

أُضيفت في: astro@2.4.0

context.locals is an object used to store and access arbitrary information during the lifecycle of a request.

Middleware functions can read and write the values of context.locals:

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Default Title";
  }
  return next();
}

API endpoints can only read information from context.locals:

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Default Title"
}

`context.getActionResult()`

Type: (action: TAction) => ActionReturnType<TAction> | undefined

أُضيفت في: astro@4.15.0 تجريبي

context.getActionResult() is a function that returns the result of an Action submission. This accepts an action function as an argument (e.g. actions.logout), and returns a data or error object when a submission is received. Otherwise, it will return undefined.

`context.callAction()`

أُضيفت في: astro@4.15.0 تجريبي

context.callAction() is a function used to call an Action handler directly from your Astro component. This function accepts an Action function as the first argument (e.g. actions.logout) and any input that action receives as the second argument. It returns the result of the action as a promise.

Endpoint Context

Endpoint functions receive a context object as the first parameter. It mirrors many of the Astro global properties.

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`getStaticPaths()`

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

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.

It can also be used in static file endpoints for dynamic routing.

`params`

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 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' } }
  ];
}

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

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

Data Passing with `props`

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:

`paginate()`

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.

paginate() has the following arguments:

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

The pagination `page` prop

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`

Type: Array

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

`page.start`

Type: number

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

`page.end`

Type: number

Index of last item on current page.

`page.size`

Type: number
Default: 10

How many items per-page.

`page.total`

Type: number

The total number of items across all pages.

`page.currentPage`

Type: number

The current page number, starting with 1.

`page.lastPage`

Type: number

The total number of pages.

`page.url.current`

Type: string

Get the URL of the current page (useful for canonical URLs).

`page.url.prev`

Type: string | undefined

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

`page.url.next`

Type: string | undefined

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

`page.url.first`

Type: string | undefined

أُضيفت في: 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`

Type: string | undefined

أُضيفت في: 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.

`import.meta`

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, like a component that should only be rendered in the client:

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

Images (`astro:assets`)

`getImage()`

Type: (options: UnresolvedImageTransform) => Promise<GetImageResult>

The getImage() function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an API Route. It also allows you to create your own custom <Image /> component.

getImage() takes an options object with the same properties as the Image component (except alt).

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>

It returns an object with the following type:

type GetImageResult = {
  /* Additional HTML attributes needed to render the image (width, height, style, etc..) */
  attributes: Record<string, any>;
  /* Validated parameters passed */
  options: ImageTransform;
  /* Original parameters passed */
  rawOptions: ImageTransform;
  /* Path to the generated image */
  src: string;
  srcSet: {
    /* Generated values for srcset, every entry has a url and a size descriptor */
    values: SrcSetValue[];
    /* A value ready to use in`srcset` attribute */
    attribute: string;
  };
}

Content Collections (`astro:content`)

أُضيفت في: astro@2.0.0

Content collections offer APIs to configure and query your Markdown or MDX documents in src/content/. For features and usage examples, see our content collections guide.

`defineCollection()`

Type: (input: CollectionConfig) => CollectionConfig

defineCollection() is a utility to configure a collection in a src/content/config.* file.

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Expose your defined collection to Astro
// with the `collections` export
export const collections = { blog };

This function accepts the following properties:

`type`

Type: 'content' | 'data'
Default: 'content'

أُضيفت في: astro@2.5.0

type is a string that defines the type of entries stored within a collection:

'content' - for content-authoring formats like Markdown (.md), MDX (.mdx), or Markdoc (.mdoc)
'data' - for data-only formats like JSON (.json) or YAML (.yaml)

`schema`

Type: ZodType | (context: SchemaContext) => ZodType

schema is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use a Zod validator.

See the Content Collection guide for example usage.

`reference()`

Type: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

أُضيفت في: astro@2.5.0

The reference() function is used in the content config to define a relationship, or “reference,” from one collection to another. This accepts a collection name and validates the entry identifier(s) specified in your content frontmatter or data file.

This example defines references from a blog author to the authors collection and an array of related posts to the same blog collection:

import { defineCollection, reference, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // Reference a single author from the `authors` collection by `id`
    author: reference('authors'),
    // Reference an array of related posts from the `blog` collection by `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

See the Content Collection guide for example usage.

`getCollection()`

Type: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

getCollection() is a function that retrieves a list of content collection entries by collection name.

It returns all items in the collection by default, and accepts an optional filter function to narrow by entry properties. This allows you to query for only some items in a collection based on id, slug, or frontmatter values via the data object.

---
import { getCollection } from 'astro:content';

// Get all `src/content/blog/` entries
const allBlogPosts = await getCollection('blog');

// Only return posts with `draft: true` in the frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

See the Content Collection guide for example usage.

`getEntry()`

أُضيفت في: astro@2.5.0

Types:

(collection: string, contentSlugOrDataId: string) => CollectionEntry<collection>
({ collection: string, id: string }) => CollectionEntry<collection>
({ collection: string, slug: string }) => CollectionEntry<collection>

getEntry() is a function that retrieves a single collection entry by collection name and either the entry id (for type: 'data' collections) or entry slug (for type: 'content' collections). getEntry() can also be used to get referenced entries to access the data, body, or render() properties:

---
import { getEntry } from 'astro:content';

// Get `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Get `src/content/captains/picard.yaml`
const picardProfile = await getEntry('captains', 'picard');

// Get the profile referenced by `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

See the Content Collections guide for examples of querying collection entries.

`getEntries()`

أُضيفت في: astro@2.5.0

Types:

(Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>
(Array<{ collection: string, slug: string }>) => Array<CollectionEntry<collection>>

getEntries() is a function that retrieves multiple collection entries from the same collection. This is useful for returning an array of referenced entries to access their associated data, body, and render() properties.

---
import { getEntries } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// Get related posts referenced by `data.relatedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`getEntryBySlug()`

Type: (collection: string, slug: string) => Promise<CollectionEntry<collection>>

getEntryBySlug() is a function that retrieves a single collection entry by collection name and entry slug.

---
import { getEntryBySlug } from 'astro:content';

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

See the Content Collection guide for example usage.

`getDataEntryById()`

Type: (collection: string, id: string) => Promise<CollectionEntry<collection>>

أُضيفت في: astro@2.5.0

getDataEntryById() is a function that retrieves a single collection entry by collection name and entry id.

---
import { getDataEntryById } from 'astro:content';

const picardProfile = await getDataEntryById('captains', 'picard');
---

Collection Entry Type

Query functions including getCollection(), getEntry(), and getEntries() each return entries with the CollectionEntry type. This type is available as a utility from astro:content:

import type { CollectionEntry } from 'astro:content';

The CollectionEntry<TCollectionName> type is an object with the following values. TCollectionName is the name of the collection you’re querying (e.g. CollectionEntry<'blog'>).

`id`

Available for: type: 'content' and type: 'data' collections
Example Types:

content collections: 'entry-1.md' | 'entry-2.md' | ...
data collections: 'author-1' | 'author-2' | ...

A unique ID using the file path relative to src/content/[collection]. Enumerates all possible string values based on the collection entry file paths. Note that collections defined as type: 'content' include the file extension in their ID, while collections defined as type: 'data' do not.

`collection`

Available for: type: 'content' and type: 'data' collections
Example Type: 'blog' | 'authors' | ...

The name of a top-level folder under src/content/ in which entries are located. This is the name used to reference the collection in your schema, and in querying functions.

`data`

Available for: type: 'content' and type: 'data' collections
Type: CollectionSchema<TCollectionName>

An object of frontmatter properties inferred from your collection schema (see defineCollection() reference). Defaults to any if no schema is configured.

`slug`

Available for: type: 'content' collections only
Example Type: 'entry-1' | 'entry-2' | ...

A URL-ready slug for Markdown or MDX documents. Defaults to the id without the file extension, but can be overridden by setting the slug property in a file’s frontmatter.

`body`

Available for: type: 'content' collections only
Type: string

A string containing the raw, uncompiled body of the Markdown or MDX document.

`render()`

Available for: type: 'content' collections only
Type: () => Promise<RenderedEntry>

A function to compile a given Markdown or MDX document for rendering. This returns the following properties:

<Content /> - A component used to render the document’s contents in an Astro file.
headings - A generated list of headings, mirroring Astro’s getHeadings() utility on Markdown and MDX imports.
remarkPluginFrontmatter - The modified frontmatter object after any remark or rehype plugins have been applied. Set to type any.

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

See the Content Collection guide for example usage.

Middleware (`astro:middleware`)

أُضيفت في: astro@2.6.0

Middleware allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. For features and usage examples, see our middleware guide.

`onRequest()`

Type: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

A required exported function from src/middleware.js that will be called before rendering every page or API route. It receives two arguments: context and next(). onRequest() must return a Response: either directly, or by calling next().

export function onRequest (context, next) {
    // intercept response data from a request
    // optionally, transform the response
    // return a Response directly, or the result of calling `next()`
    return next();
};

`context`

Type: APIContext

The first argument of onRequest() is a context object. It mirrors many of the Astro global properties.

See Endpoint contexts for more information about the context object.

`next()`

Type: (rewritePayload?: string | URL | Request) => Promise<Response>

The second argument of onRequest() is a function that calls all the subsequent middleware in the chain and returns a Response. For example, other middleware could modify the HTML body of a response and awaiting the result of next() would allow your middleware to respond to those changes.

Since Astro v4.13.0, next() accepts an optional URL path parameter in the form of a string, URL, or Request to rewrite the current request without retriggering a new rendering phase.

`sequence()`

Type: (...handlers: MiddlewareHandler[]) => MiddlewareHandler

A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed.

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

export const onRequest = sequence(validation, auth, greeting);

`createContext()`

Type: (context: CreateContext) => APIContext

أُضيفت في: astro@2.8.0

A low-level API to create an APIContextto be passed to an Astro middleware onRequest() function.

This function can be used by integrations/adapters to programmatically execute the Astro middleware.

`trySerializeLocals()`

Type: (value: unknown) => string

أُضيفت في: astro@2.8.0

A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.

Internationalization (`astro:i18n`)

أُضيفت في: astro@3.5.0

This module provides functions to help you create URLs using your project’s configured locales.

Creating routes for your project with the i18n router will depend on certain configuration values you have set that affect your page routes. When creating routes with these functions, be sure to take into account your individual settings for:

Also, note that the returned URLs created by these functions for your defaultLocale will reflect your i18n.routing configuration.

For features and usage examples, see our i18n routing guide.

`getRelativeLocaleUrl()`

Type: (locale: string, path?: string, options?: GetLocaleOptions) => string

Use this function to retrieve a relative path for a locale. If the locale doesn’t exist, Astro throws an error.

---
getRelativeLocaleUrl("fr");
// returns /fr

getRelativeLocaleUrl("fr", "");
// returns /fr

getRelativeLocaleUrl("fr", "getting-started");
// returns /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// returns /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// returns /blog/fr_CA/getting-started
---

`getAbsoluteLocaleUrl()`

Type: (locale: string, path: string, options?: GetLocaleOptions) => string

Use this function to retrieve an absolute path for a locale when [site] has a value. If [site] isn’t configured, the function returns a relative URL. If the locale doesn’t exist, Astro throws an error.

---
// If `site` is set to be `https://example.com`

getAbsoluteLocaleUrl("fr");
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", "");
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", "getting-started");
// returns https://example.com/fr/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// returns https://example.com/blog/fr-ca/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// returns https://example.com/blog/fr_CA/getting-started
---

`getRelativeLocaleUrlList()`

Type: (path?: string, options?: GetLocaleOptions) => string[]

Use this like getRelativeLocaleUrl to return a list of relative paths for all the locales.

`getAbsoluteLocaleUrlList()`

Type: (path?: string, options?: GetLocaleOptions) => string[]

Use this like getAbsoluteLocaleUrl to return a list of absolute paths for all the locales.

`getPathByLocale()`

Type: (locale: string) => string

A function that returns the path associated to one or more codes when custom locale paths are configured.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getPathByLocale("fr"); // returns "french"
getPathByLocale("fr-CA"); // returns "french"
---

`getLocaleByPath()`

Type: (path: string) => string

A function that returns the code associated to a locale path.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getLocaleByPath("french"); // returns "fr" because that's the first code configured
---

`redirectToDefaultLocale()`

Type: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

أُضيفت في: astro@4.6.0

A function that returns a Response that redirects to the defaultLocale configured. It accepts an optional valid redirect status code.

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  if (context.url.pathname.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(context, 302);
  }
})

`redirectToFallback()`

Type: (context: APIContext, response: Response) => Promise<Response>

أُضيفت في: astro@4.6.0

A function that allows you to use your i18n.fallback configuration in your own middleware.

import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();
  if (response.status >= 300) {
    return redirectToFallback(context, response)
  }
  return response;
})

`notFound()`

Type: (context: APIContext, response?: Response) => Promise<Response> | undefined

أُضيفت في: astro@4.6.0

Use this function in your routing middleware to return a 404 when:

the current path isn’t a root. e.g. / or /<base>
the URL doesn’t contain a locale

When a Response is passed, the new Response emitted by this function will contain the same headers of the original response.

import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  const pathNotFound = notFound(context);
  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
})

`middleware()`

Type: (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

أُضيفت في: astro@4.6.0

A function that allows you to programmatically create the Astro i18n middleware.

This is use useful when you still want to use the default i18n logic, but add only a few exceptions to your website.

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // Custom logic after resolving the response.
  // It's possible to catch the response coming from Astro i18n middleware.

  return response;
});

export const onRequest = sequence(customLogic, middleware({
  prefixDefaultLocale: true,
  redirectToDefaultLocale: false
}))

`requestHasLocale()`

Type: (context: APIContext) => boolean

أُضيفت في: astro@4.6.0

Checks whether the current URL contains a configured locale. Internally, this function will use APIContext#url.pathname.

import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  if (requestHasLocale(context)) {
    return next();
  }
  return new Response("Not found", { status: 404 });
})

Actions (astro:actions )

أُضيفت في: astro@4.15.0 تجريبي

Actions are backend functions used for type-safe server-to-client communication. All utilities to define and call actions are exposed by the astro:actions module. For examples and usage instructions, see the Actions guide.

`defineAction()`

أُضيفت في: astro@4.15.0 تجريبي

The defineAction() utility is used to define new actions from the src/actions/index.ts file. This accepts a handler() function containing the server logic to run, and an optional input property to validate input parameters at runtime.

export const server = {
    getGreeting: defineAction({
    input: z.object({
      name: z.string(),
    }),
    handler: async (input) => {
      return `Hello, ${input.name}!`
    }
  })
}

`handler()` property

أُضيفت في: astro@4.15.0 تجريبي

defineAction() accepts a handler() function containing the server logic to run when the action is called. This function can return data that is automatically serialized and sent to the caller.

Return values are parsed using the devalue library. This supports JSON values, along with instances of Date(), Map(), Set(), or URL().

`input` validator

أُضيفت في: astro@4.15.0 تجريبي

The optional input property accepts a Zod validator to validate handler inputs at runtime. If the action fails to validate, a BAD_REQUEST error is returned and the handler is not called.

If used with accept: 'form', input must use the z.object() validator.

Extension functions including .refine(), .transform(), and .pipe() are also supported on this object. The following validators are supported for form data fields:

Inputs of type number can be validated using z.number()
Inputs of type checkbox can be validated using z.boolean()
Inputs of type file can be validated using z.instanceof(File)
Multiple inputs of the same name can be validated using z.array(/* validator */)
All other inputs can be validated using z.string()

`isInputError()`

Type: (error?: unknown | ActionError) => boolean

أُضيفت في: astro@4.15.0 تجريبي

The isInputError() utility is used to check whether an ActionError is an input validation error. When the input validator is a z.object(), input errors include a fields object with error messages grouped by name.

See the form input errors guide for more on using isInputError().

`ActionError`

أُضيفت في: astro@4.15.0 تجريبي

The ActionError() constructor is used to create errors thrown by an action handler. This accepts a code property describing the error that occurred (example: "UNAUTHORIZED"), and an optional message property with further details.

`code`

أُضيفت في: astro@4.15.0 تجريبي

The code property accepts human-readable versions of all HTTP status codes. The following codes are supported:

BAD_REQUEST (400): The client sent invalid input. This error is thrown when an action input validator fails to validate.
UNAUTHORIZED (401): The client lacks valid authentication credentials.
FORBIDDEN (403): The client is not authorized to access a resource.
NOT_FOUND (404): The server cannot find the requested resource.
METHOD_NOT_SUPPORTED (405): The server does not support the requested method.
TIMEOUT (408): The server timed out while processing the request.
CONFLICT (409): The server cannot update a resource due to a conflict.
PRECONDITION_FAILED (412): The server does not meet a precondition of the request.
PAYLOAD_TOO_LARGE (413): The server cannot process the request because the payload is too large.
UNSUPPORTED_MEDIA_TYPE (415): The server does not support the request’s media type. Note: Actions already check the Content-Type header for JSON and form requests, so you likely won’t need to raise this code manually.
UNPROCESSABLE_CONTENT (422): The server cannot process the request due to semantic errors.
TOO_MANY_REQUESTS (429): The server has exceeded a specified rate limit.
CLIENT_CLOSED_REQUEST (499): The client closed the request before the server could respond.
INTERNAL_SERVER_ERROR (500): The server failed unexpectedly.
NOT_IMPLEMENTED (501): The server does not support the requested feature.
BAD_GATEWAY (502): The server received an invalid response from an upstream server.
SERVICE_UNAVAILABLE (503): The server is temporarily unavailable.
GATEWAY_TIMEOUT (504): The server received a timeout from an upstream server.

`message`

أُضيفت في: astro@4.15.0 تجريبي

The message property accepts a string. (e.g. “User must be logged in.“)

Built-in Components

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';.

You can reference the Props of these components using the ComponentProp type utility.

`<Code />`

---
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 />
<!-- Optional: Output inline code. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- Optional: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

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, languages, transformers, and default colors by passing them to the theme, lang, transformers, and defaultColor attributes respectively.

Transformers

أُضيفت في: astro@4.11.0

Shiki transformers can optionally be applied to code by passing them in through the transformers property as an array. Since Astro v4.14.0, you can also provide a string for Shiki’s meta attribute to pass options to transformers.

Note that transformers only applies classes and you must provide your own CSS rules to target the elements of your code block.

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}" />

  <style is:global>
    pre.has-focused .line:not(.focused) {
      filter: blur(1px);
    }
  </style>

`<Fragment />`

A component used with set:* directives to render HTML content without any additional wrapping elements:

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

See more about using fragments in Astro syntax.

`<Prism />`

To use the Prism highlighter component, first install the @astrojs/prism package:

npm install @astrojs/prism

pnpm add @astrojs/prism

yarn add @astrojs/prism

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

`<Image />`

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description of my image." />

<!-- Output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

Properties

src (required)
alt (required)
width and height (required for public/ and remote images)
format
quality
densities
widths

In addition to the properties above, the <Image /> component accepts all properties accepted by the HTML <img> tag.

See more in the Images Guide.

`<Picture />`

أُضيفت في: astro@3.3.0

Use the built-in <Picture /> Astro component to display a responsive image with multiple formats and/or sizes.

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---

<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- Output -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

See more in the Images Guide.

Properties

<Picture /> accepts all the properties of the <Image /> component, plus the following:

`formats`

An array of image formats to use for the <source> tags. By default, this is set to ['webp'].

`fallbackFormat`

Format to use as a fallback value for the <img> tag. Defaults to .png for static images, .gif for animated images, and .svg for SVG files.

`pictureAttributes`

An object of attributes to be added to the <picture> tag. Use this property to apply attributes to the outer <picture> element itself. Attributes applied to the <Picture /> component directly will apply to the inner <img> element, except for those used for image transformation.

`<Content />`

A generic component used to render the content of a content collection entry.

First, query one or more entries using getCollection() or getEntry(). Then, the entry.render() function can return the <Content /> component for use in a .astro file template.

---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'post-1');
const { Content } = await entry.render();
---
<p>Published on: {entry.data.published.toDateString()}</p>
<Content />

`<ViewTransitions />`

أُضيفت في: astro@2.9.0

Opt in to using view transitions on individual pages by importing and adding the <ViewTransitions /> routing component to <head> on every desired page.

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

See more about how to control the router and add transition directives to page elements and components.

`<Debug />`

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

ساهم

المجتمع

API Reference

Astro global

Astro.glob()

Markdown Files

Astro Files

Other Files

Astro.props

Astro.params

Astro.request

Astro.response

Astro.cookies

get

has

set

delete

merge

headers

AstroCookie

value

json

number

boolean

AstroCookieGetOptions

decode

AstroCookieSetOptions

domain

expires

httpOnly

maxAge

path

sameSite

secure

encode

Astro.redirect()

Astro.rewrite()

Astro.url

Astro.clientAddress

Astro.site

Astro.generator

Astro.slots

Astro.slots.has()

Astro.slots.render()

Astro.self

Astro.locals

Astro.preferredLocale

Astro.preferredLocaleList

Astro.currentLocale

Astro.getActionResult()

Astro.callAction()

Endpoint Context

context.params

context.props

context.request

context.cookies

context.url

context.clientAddress

context.site

context.generator

context.redirect()

context.rewrite()

context.locals

context.getActionResult()

context.callAction()

Endpoint Context

getStaticPaths()

params

Data Passing with props

paginate()

The pagination page prop

page.data

page.start

page.end

page.size

page.total

page.currentPage

page.lastPage

page.url.current

page.url.prev

page.url.next

page.url.first

`Astro` global

`Astro.glob()`

`Astro.props`

`Astro.params`

`Astro.request`

`Astro.response`

`Astro.cookies`

`get`

`has`

`set`

`delete`

`merge`

`headers`

`AstroCookie`

`value`

`json`

`number`

`boolean`

`AstroCookieGetOptions`

`decode`

`AstroCookieSetOptions`

`domain`

`expires`

`httpOnly`

`maxAge`

`path`

`sameSite`

`secure`

`encode`

`Astro.redirect()`

`Astro.rewrite()`

`Astro.url`

`Astro.clientAddress`

`Astro.site`

`Astro.generator`

`Astro.slots`

`Astro.slots.has()`

`Astro.slots.render()`

`Astro.self`

`Astro.locals`

`Astro.preferredLocale`

`Astro.preferredLocaleList`

`Astro.currentLocale`

`Astro.getActionResult()`

`Astro.callAction()`

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.rewrite()`

`context.locals`

`context.getActionResult()`

`context.callAction()`

`getStaticPaths()`

`params`

Data Passing with `props`

`paginate()`

The pagination `page` prop

`page.data`

`page.start`

`page.end`

`page.size`

`page.total`

`page.currentPage`

`page.lastPage`

`page.url.current`

`page.url.prev`

`page.url.next`

`page.url.first`

`page.url.last`

`import.meta`

Images (`astro:assets`)

`getImage()`

Content Collections (`astro:content`)

`defineCollection()`