> ## 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.
# Assets API
> API reference for Astro's built-in image optimization and asset handling
Astro provides built-in image optimization and asset handling through the `astro:assets` module.
## Importing
```typescript theme={null}
import { Image, Picture, getImage } from 'astro:assets';
```
## Image Component
The `` component optimizes images and generates responsive image markup.
```astro theme={null}
import { Image } from 'astro:assets';
import myImage from '../assets/my-image.png';
```
### Props
Image source. Can be an imported image or a URL string.
```astro theme={null}
import localImage from '../images/photo.jpg';
```
Alternative text for the image. Required for accessibility.
```astro theme={null}
```
Desired width of the image. Sets the `width` attribute and resizes the image.
```astro theme={null}
```
Desired height of the image. Sets the `height` attribute and resizes the image if `width` is not provided.
```astro theme={null}
```
Output format for the image.
**Default:** `'webp'`
```astro theme={null}
```
Quality preset or numeric value (0-100) for the output image.
```astro theme={null}
```
Pixel densities to generate for the image srcset.
```astro theme={null}
```
Widths to generate for the image srcset.
```astro theme={null}
```
How the image should be resized to fit the dimensions.
**Default:** `'cover'`
```astro theme={null}
```
Position of the image when using `fit`. Similar to CSS `object-position`.
```astro theme={null}
```
Background color to use when converting transparent images to non-transparent formats.
```astro theme={null}
```
Automatically infer width and height from the source image.
**Default:** `true` for local images
```astro theme={null}
```
### HTML Attributes
All standard HTML `` attributes are also supported:
```astro theme={null}
```
### Example
```astro theme={null}
---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---
```
## Picture Component
The `` component generates a `` element with multiple sources and formats.
```astro theme={null}
import { Picture } from 'astro:assets';
import myImage from '../assets/my-image.png';
```
### Props
Array of image formats to generate. The component will create a `` for each format.
**Default:** `['webp']`
```astro theme={null}
```
Format to use for the fallback `` element.
**Default:** `'png'`
```astro theme={null}
```
Attributes to apply to the `` element.
```astro theme={null}
```
All other props from the `Image` component are also supported.
### Example
```astro theme={null}
---
import { Picture } from 'astro:assets';
import headerImage from '../assets/header.png';
---
```
## getImage
Programmatically get optimized image data without rendering an `` tag.
```typescript theme={null}
getImage(options: ImageTransform): Promise
```
Image transformation options.
Image source.
Desired width.
Desired height.
Output format.
Image quality.
All other Image component props are also supported.
Object containing optimized image data.
URL of the optimized image.
Srcset data for responsive images.
Array of srcset values.
Formatted srcset attribute string.
HTML attributes for the image (width, height, etc.).
Processed transformation options.
### Example
```astro theme={null}
---
import { getImage } from 'astro:assets';
import myImage from '../assets/my-image.png';
const optimizedImage = await getImage({
src: myImage,
width: 800,
format: 'webp',
quality: 'high',
});
---
```
## ImageMetadata Type
Type for imported images.
```typescript theme={null}
type ImageMetadata = {
src: string;
width: number;
height: number;
format: 'png' | 'jpg' | 'jpeg' | 'tiff' | 'webp' | 'gif' | 'svg' | 'avif';
};
```
### Example
```astro theme={null}
---
import type { ImageMetadata } from 'astro';
import logo from '../assets/logo.png';
const image: ImageMetadata = logo;
console.log(image.width); // 800
console.log(image.height); // 600
console.log(image.format); // 'png'
---
```
## Remote Images
To use remote images, configure `image.domains` or `image.remotePatterns` in your Astro config:
```javascript theme={null}
// astro.config.mjs
export default defineConfig({
image: {
domains: ['example.com'],
remotePatterns: [{ protocol: 'https' }],
},
});
```
Then use remote URLs with the Image component:
```astro theme={null}
```