Images

Astro provides several ways for you to use images on your site, whether they are stored locally inside your project, linked to from an external URL, or managed in a CMS or CDN!

We recommend that local images are kept in src/ when possible so that Astro can transform, optimize and bundle them. Files in the /public directory are always served or copied into the build folder as-is, with no processing.

Your local images stored in src/ can be used by all files in your project: .astro, .md, .mdx, .mdoc, and other UI frameworks. Images can be stored in any folder, including alongside your content.

Store your images in the public/ folder if you want to avoid any processing or to have a direct public link to them.

You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform.

For extra protection when dealing with external sources, remote images will only be processed from authorized image sources specified in your configuration. However, any remote images can be displayed.

Astro can fetch your data remotely using APIs or display images from their full URL path. See our CMS guides for examples of integrating common services.

In .astro files, local images must be imported into the file in order to be used. Remote and public/ images do not require importing.

Import and use Astro’s built-in <Image /> component for optimized images using astro:assets. Alternatively, Astro syntax supports writing an HTML <img> tag directly, which skips image processing.

Use the built-in <Image /> Astro component to display optimized versions of your local images and configured remote images.

Images in the public/ folder, as well as remote images not specifically configured in your project, can also be used with the Image component, but will not be processed.

<Image /> can transform a local or authorized remote image’s dimensions, file type, and quality for control over your displayed image. The resulting <img> tag includes alt, loading, and decoding attributes and infers image dimensions to avoid Cumulative Layout Shift (CLS).

Currently, the built-in assets feature does not include a <Picture /> component.

Instead, you can generate images or custom components using getImage() that use the HTML image attributes srcset and sizes or the <picture> tag for art direction or to create responsive images.

The format of the src value of your image file depends on where your image file is located:

• Local images in src/ - you must also import the image using a relative file path or configure and use an import alias. Then use the import name as the src value:

  src/pages/index.astro

• Images in the public/ folder - use the image’s file path relative to the public folder:

  src/pages/index.astro

• Remote images - use the image’s full URL as the property value:

  src/pages/index.astro

Use the required alt attribute to provide a string of descriptive alt text for images.

If an image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set alt="" so that screen readers and other assistive technologies know to ignore the image.

These properties define the dimensions to use for the image.

When using local images in their original aspect ratio, the width and height can be automatically inferred from the source file and are optional.

However, both of these properties are required for remote images and images stored in your public/ folder as Astro is unable to analyze these files.

You can optionally state the image file type output to be used.

By default, the <Image /> component will produce a .webp file.

quality is an optional property that can either be:

• a preset (low, mid, high, max) that is automatically normalized between formats.
• a number from 0 to 100 (interpreted differently between formats).

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

For example, you can provide a class to the final <img> element.

Currently, there is no way to specify default values for all <Image /> components. Required attributes should be set on each individual component.

As an alternative, you can wrap these components in another Astro component for reuse. For example, you could create a component for your blog post images:

The Astro template syntax also supports writing an <img> tag directly, with full control over its final output. These images will not be processed and optimized.

It accepts all HTML <img> tag properties, and the only required property is src.

Local images must be imported from the relative path from the existing .astro file, or configure and use an import alias. Then, you can access the image’s src and other properties to use in the <img> tag.

For example, use the image’s own height and width properties to avoid CLS and improve Core Web Vitals.

Imported image assets match the following signature:

For images located within public/ use the image’s file path relative to the public folder as the src value:

For remote images, use the image’s full URL as the src value:

The <Image /> component optimizes your image and infers width and height (of local images) based on the original aspect ratio to avoid CLS. But, it only works with certain formats and does not provide a <picture> element, nor does it support srcset.

Use the HTML <img> element when you cannot use the <Image /> component, for example:

• for unsupported image formats
• when you do not want your image optimized by Astro
• to access and change the src attribute dynamically client-side

You can configure lists of authorized image source URL domains and patterns for image optimization using image.domains and image.remotePatterns. This configuration is an extra layer of safety to protect your site when showing images from an external source.

Remote images from other sources will not be optimized, but using the <Image /> component for these images will prevent Cumulative Layout Shift (CLS).

For example, the following configuration will only allow remote images from astro.build to be optimized:

The following configuration will only allow remote images from HTTPS hosts:

Image CDNs work with all Astro image options. Use an image’s full URL as the src attribute in the <Image /> component, an <img> tag, or in Markdown notation. For image optimization with remote images, also configure your authorized domains or URL patterns.

Alternatively, if the CDN provides a Node.js SDK, you can use that in your project. For example, Cloudinary’s SDK can generate an <img> tag with the appropriate src for you.

Use standard Markdown ![alt](src) syntax in your .md files. This syntax works with Astro’s Image Service API to optimize your local images and authorized remote images.

The <img> tag is not supported for local images, and the <Image /> component is unavailable in .md files.

If you require more control over your image attributes, we recommend using the .mdx file format, which allows you to include Astro’s <Image /> component or a JSX <img /> tag in addition to the Markdown syntax. Use the MDX integration to add support for MDX to Astro.

You can use Astro’s <Image /> component and JSX <img /> tags in your .mdx files by importing both the component and your image. Use them just as they are used in .astro files.

Additionally, there is support for standard Markdown ![alt](src) syntax with no import required.

You can declare an associated image for a content collections entry, such as a blog post’s cover image, in your frontmatter using its path relative to the current folder:

The image helper for the content collections schema lets you validate the image metadata using Zod.

The image will be imported and transformed into metadata, allowing you to pass it as a src to <Image/>, <img>, or getImage().

The example below shows a blog index page that renders the cover photo and title of each blog post from the schema above:

When adding images in a UI framework component, use the framework’s own image syntax to render an image (e.g. <img /> in JSX, <img> in Svelte).

Local images must first be imported to access their image properties such as src.

The <Image /> component, like any other Astro component, is unavailable to UI framework components.

But, you can pass the static content generated by <Image /> to a framework component inside a .astro file as children or using a named <slot/>:

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

It returns an object with the following properties:

Not all users can see images in the same way, so accessibility is an especially important concern when using images. Use the alt attribute to provide descriptive alt text for images.

This attribute is required for the <Image /> component. <Image /> will throw an error if no alt text is provided.

If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set alt="" so that screen readers know to ignore the image.

Sharp is the default image service used for astro:assets.

If you would prefer to use Squoosh to transform your images, update your config with the following:

There are several third-party community image integrations for optimizing and working with images in your Astro project.

astro:assets is no longer behind an experimental flag in Astro v3.0.

<Image /> is now a built-in component and the previous @astrojs/image integration has been removed.

These and other accompanying changes to using images in Astro may cause some breaking changes when you upgrade your Astro project from an earlier version.

Please follow the instructions below as appropriate to upgrade an Astro v2.x project to v3.0.

If you had previously enabled the experimental flag for astro:assets, you will need to update your project for Astro v3.0 which now includes assets features by default.

Remove the experimental flag:

If necessary, also update your src/env.d.ts file to replace the astro/client-image reference with astro/client:

This import alias is no longer included by default with astro:assets. If you were using this alias with experimental assets, you must convert them to relative file paths, or create your own import aliases.

Astro v3.0 allows astro:assets to work without errors in Cloudflare, Deno, Vercel Edge and Netlify Edge, which do not support Astro’s built-in Squoosh and Sharp image optimization. Note that Astro does not perform any image transformation and processing in these environments. However, you can still enjoy the other benefits of using astro:assets, including no Cumulative Layout Shift (CLS), the enforced alt attribute, and a consistent authoring experience.

If you previously avoided using astro:assets because of these constraints, you can now use them without issues. You can configure the no-op image service to explicitly opt-in to this behavior:

See the Images guide to help you decide where to store your images. You may wish to take advantage of new options for storing your images with the added flexibility astro:assets brings. For example, relative images from your project src/ can now be referenced in Markdown, MDX, and Markdoc using standard Markdown ![alt](src) syntax.

Previously, importing an image would return a simple string with the path of the image. Now, imported image assets match the following signature:

You must update the src attribute of any existing <img> tags (including any images in UI framework components) and you may also update other attributes that are now available to you from the imported image.

Relative images from your project src/ can now be referenced in Markdown, MDX, and Markdoc using standard Markdown ![alt](src) syntax.

This allows you to move your images from the public/ directory to your project src/ where they will now be processed and optimized. Your existing images in public/ and remote images are still valid but are not optimized by Astro’s build process.

If you require more control over your image attributes, we recommend using the .mdx file format, which allows you to include Astro’s <Image /> component or a JSX <img /> tag in addition to the Markdown syntax. Use the MDX integration to add support for MDX to Astro.

If you were using the image integration in Astro v2.x, complete the following steps:

1. Remove the @astrojs/image integration.

   You must remove the integration by uninstalling and then removing it from your astro.config.mjs file.

   astro.config.mjs

2. Update types (if required).

   If you had special types configured for @astrojs/image in src/env.d.ts, you may need to change them back to the default Astro types if your upgrade to v3 did not complete this step for you.

   src/env.d.ts

   Similarly, update tsconfig.json if necessary:

   tsconfig.json

3. Migrate any existing <Image /> components.

   Change all import statements from @astrojs/image/components to astro:assets in order to use the new built-in <Image /> component.

   Remove any component attributes that are not currently supported image asset properties.

   For example, aspectRatio is no longer supported, as it is now automatically inferred from the width and height attributes.

   src/components/MyComponent.astro

4. Remove any existing <Picture /> components.

   Currently, the built-in assets feature does not include a <Picture /> component.

   Instead, you can use the HTML image attributes srcset and sizes or the <picture> tag for art direction or to create responsive images.

5. Choose a default image service.

   Sharp is now the default image service used for astro:assets. If you would like to use Sharp, no configuration is required.

   If you would prefer to use Squoosh to transform your images, update your config with the following image.service option:

   astro.config.mjs

You can now declare an associated image for a content collections entry, such as a blog post’s cover image, in your frontmatter using its path relative to the current folder.

The new image helper for content collections lets you validate the image metadata using Zod. Learn more about how to use images in content collections

In Astro v3.0, if you have to preserve the old import behavior for images and require a string representation of the image’s URL, append ?url to the end of your image path when importing it. For example:

This approach ensures you obtain the URL string. Keep in mind that during development, Astro uses a src/ path, but upon building, it generates hashed paths like /_astro/cat.a6737dd3.png.

If you prefer to work directly with the image object itself, you can access the .src property. This approach is best for tasks like managing image dimensions for Core Web Vitals metrics and preventing CLS.

If you are transitioning into the new import behavior, combining ?url and .src methods might be the right method for seamless image handling.