Images

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

Astro uses HTML <img> elements to display images, and all HTML image attributes are supported.

The src attribute is required, and its format will depend on where your images are stored, and whether you have enabled experimental support for assets:

---
import rocket from '../images/rocket.svg';
---
<!-- Remote image on another server -->
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro">

<!-- Local image stored at public/assets/stars.png -->
<img src="/assets/stars.png" alt="A starry night sky.">

<!-- Local image stored at src/images/rocket.svg -->
<img src={rocket} alt="A rocketship in space."/>

You can use standard Markdown ![]() syntax or standard HTML <img> tags in your .md files for images located in your public/ folder, or remote images on another server.

If you cannot keep your images in public/, we recommend enabling experimental support for assets, or using the .mdx file format, which allows you to combine imported components with Markdown-like syntax. Use the MDX integration to add support for MDX to Astro.

# My Markdown Page

<!-- Local image stored at public/assets/stars.png -->
![A starry night sky.](/assets/stars.png)
<img src="/assets/stars.png" alt="A starry night sky.">

<!-- Remote image on another server -->
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro">

You can use standard Markdown ![]() syntax or JSX <img /> tags in your .mdx files to display images from your public/ folder or remote servers.

Additionally, you can import and use images located in your project’s src/ directory, as you would in Astro components.

import rocket from '../images/rocket.svg';

# My MDX Page

// Local image stored at src/images/rocket.svg
<img src={rocket} alt="A rocketship in space."/>

// Local image stored at public/assets/stars.png
![A starry night sky.](/assets/stars.png)
<img src="/assets/stars.png" alt="A starry night sky." />

// Remote image on another server
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro" />

When adding images in a UI framework component (e.g React, Svelte), use the image syntax appropriate for that particular component’s framework.

Your images stored in src/ can be used by components (.astro, .mdx and other UI frameworks) but not in Markdown files.

We recommend that you keep your images in public/ or store them remotely if you must use Markdown files.

Import them from a relative file path or import alias in any component file and then use the import as the image’s src attribute.

---
// Access images in `src/images/`
import logo from '../images/logo.png';
---
<img src={logo} width="40" alt="Astro" />

Your images stored in public/ can be used by components (.astro, .mdx and other UI frameworks) and also Markdown files.

However, files in the /public directory are always served or copied as-is, with no processing. If you are using images outside of Markdown files, we recommend that local images are kept in src/ when possible so that Astro can transform, optimize and bundle them.

The src attribute is relative to the public folder. In Markdown, you can also use the ![]() notation.

---
// Access images in `public/images/`
---
<img src="/images/logo.png" />

See the Assets (Experimental) guide for enabling experimental use of the /assets/ folder.

This will require you to update your existing images, remove the current Astro image integration, and will also require additional manual changes to take advantage of some of its new features.

For documentation on using @astrojs/image in Astro v2, please see the @astrojs/image package documentation

Image CDNs work with Astro. Use an image’s full URL as the src attribute in an <img> tag or Markdown notation.

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

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 integration’s <Image /> and <Picture /> components. These components 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.

In addition to the official @astrojs/image integration, there are several third-party community image integrations for optimizing and working with images in your Astro project.