> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.
# Asset Handling
> Learn how to optimize and manage images and other assets in Astro
Astro provides powerful built-in asset handling for images and other media. The assets system optimizes images automatically, generates multiple formats, and provides a great developer experience with type safety.
## Image Component
The `Image` component from `astro:assets` optimizes images at build time with automatic format conversion, resizing, and lazy loading.
```astro src/pages/index.astro theme={null}
---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.png';
---
```
Images are optimized during the build process, generating multiple sizes and formats for better performance.
### Local Images
Import local images from your project to get type safety and automatic optimization:
```astro theme={null}
---
import { Image } from 'astro:assets';
import profilePic from '../assets/profile.jpg';
import logo from '../assets/logo.png';
---
```
### Remote Images
For remote images, specify dimensions explicitly:
```astro theme={null}
---
import { Image } from 'astro:assets';
---
```
Remote images require explicit `width` and `height` attributes. Configure allowed remote domains in your config.
## Image Properties
The `Image` component accepts various properties for optimization:
Image source - local import or remote URL
Alternative text for accessibility
Target width in pixels. Required for remote images.
Target height in pixels. Required for remote images.
Output format. Defaults to optimized format.
Compression quality. Default: 'mid'
Pixel density descriptors for responsive images
Generate multiple widths for srcset
### Example with All Properties
```astro theme={null}
---
import { Image } from 'astro:assets';
import banner from '../assets/banner.jpg';
---
```
## Picture Component
Use the `Picture` component for art direction and multiple formats:
```astro theme={null}
---
import { Picture } from 'astro:assets';
import hero from '../assets/hero.jpg';
---
```
This generates:
* Multiple format versions (AVIF, WebP, JPEG)
* Multiple sizes for responsive images
* Automatic `` element with `` tags
Use `Picture` for responsive images with art direction. Use `Image` for simple cases.
## Image Service
Astro uses Sharp by default for image optimization. You can configure or replace the image service:
```js astro.config.mjs theme={null}
import { defineConfig } from 'astro/config';
export default defineConfig({
image: {
service: {
entrypoint: 'astro/assets/services/sharp',
config: {
limitInputPixels: false
}
},
// Configure remote image domains
domains: ['images.example.com'],
remotePatterns: [{ protocol: 'https' }]
}
});
```
### Available Services
High-performance Node.js image processing:
```js theme={null}
import { defineConfig } from 'astro/config';
export default defineConfig({
image: {
service: {
entrypoint: 'astro/assets/services/sharp'
}
}
});
```
Disables image optimization:
```js theme={null}
import { defineConfig } from 'astro/config';
export default defineConfig({
image: {
service: {
entrypoint: 'astro/assets/services/noop'
}
}
});
```
## getImage API
For programmatic image optimization, use the `getImage` function:
```astro theme={null}
---
import { getImage } from 'astro:assets';
import background from '../assets/background.jpg';
const optimizedImage = await getImage({
src: background,
width: 1920,
height: 1080,
format: 'webp',
quality: 'high'
});
---
Content here
```
### Return Value
The `getImage` function returns an object with:
```typescript theme={null}
interface GetImageResult {
src: string; // Optimized image URL
srcSet: {
values: string[]; // srcset values
attribute: string; // Complete srcset attribute
};
attributes: Record; // HTML attributes
options: ImageTransform; // Transform options used
}
```
## Images in Markdown
Reference images in Markdown and MDX files:
```markdown src/content/blog/post.md theme={null}
---
title: My Post
---
```
Or use the Image component in MDX:
```mdx src/content/blog/post.mdx theme={null}
---
title: My Post
---
import { Image } from 'astro:assets';
import screenshot from '../../assets/screenshot.png';
# My Post
```
## Responsive Images
Generate responsive images with multiple sizes:
```astro theme={null}
---
import { Image } from 'astro:assets';
import product from '../assets/product.jpg';
---
```
This generates:
```html theme={null}
```
## Image Layouts
Control how images scale and fit:
```astro Constrained (Default) theme={null}
```
```astro Fixed theme={null}
```
```astro Full Width theme={null}
```
Image scales down on smaller screens but never exceeds its specified width.
Best for most use cases.
Image maintains exact dimensions at all screen sizes.
Best for avatars, icons, and UI elements.
Image always fills its container width.
Best for hero images and banners.
## Background Images
Optimize background images using `getImage`:
```astro theme={null}
---
import { getImage } from 'astro:assets';
import bg from '../assets/background.jpg';
const backgroundImage = await getImage({
src: bg,
format: 'webp',
quality: 80
});
---
Hero Section
```
## Other Assets
### Fonts
Import and reference fonts:
```astro theme={null}
---
import fontFile from '../assets/fonts/custom-font.woff2';
---
```
### Videos
Reference video files:
```astro theme={null}
---
import video from '../assets/demo.mp4';
---
```
### Public Directory
For assets that shouldn't be processed, use the `public/` directory:
```
public/
favicon.ico
robots.txt
static-image.png
```
Reference them with absolute paths:
```html theme={null}
```
Files in `public/` are copied as-is to the build output without processing.
## Performance Best Practices
Enable AVIF and WebP for better compression:
```astro theme={null}
```
```astro theme={null}
```
```astro theme={null}
```
```astro theme={null}
```
## TypeScript Support
Images imports are fully typed:
```typescript theme={null}
import type { ImageMetadata } from 'astro';
import image from '../assets/image.jpg';
// image is typed as ImageMetadata
const metadata: ImageMetadata = image;
console.log(metadata.width); // number
console.log(metadata.height); // number
console.log(metadata.format); // string
console.log(metadata.src); // string
```
## Related Resources
Use images in Markdown content
Manage images in collections
Configure image service
Performance optimization guide
```
## Image Layouts
Control how images scale and fit:
```