Assets API Reference
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Hinzugefügt in:
astro@3.0.0
Astro provides built-in components and helper functions for optimizing and displaying your images. For features and usage examples, see our image guide.
Imports from astro:assets
Section titled Imports from astro:assets<Image />
Section titled <Image />Image properties
Section titled Image propertiesThe <Image />
component accepts all properties accepted by the HTML <img>
tag in addition to the properties described below.
src (required)
Section titled src (required)Type: ImageMetadata | string | Promise<{ default: ImageMetadata }>
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 thesrc
value: -
Images in the
public/
folder - use the image’s file path relative to the public folder: -
Remote images - use the image’s full URL as the property value:
alt (required)
Section titled alt (required)Type: string
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.
width and height (required for images in public/
)
Section titled width and height (required for images in public/)Type: number | undefined
These properties define the dimensions to use for the image.
When using images in their original aspect ratio, width
and height
are optional. These dimensions can be automatically inferred from image files located in src/
. For remote images, add the inferSize
attribute set to true
on the <Image />
or <Picture />
component or use inferRemoteSize()
function.
However, both of these properties are required for images stored in your public/
folder as Astro is unable to analyze these files.
densities
Section titled densitiesType: (number | `${number}x`)[] | undefined
astro@3.3.0
A list of pixel densities to generate for the image.
If provided, this value will be used to generate a srcset
attribute on the <img>
tag. Do not provide a value for widths
when using this value.
Densities that are equal to widths larger than the original image will be ignored to avoid upscaling the image.
widths
Section titled widthsType: number[] | undefined
astro@3.3.0
A list of widths to generate for the image.
If provided, this value will be used to generate a srcset
attribute on the <img>
tag. A sizes
property must also be provided.
Do not provide a value for densities
when using this value. Only one of these two values can be used to generate a srcset
.
Widths that are larger than the original image will be ignored to avoid upscaling the image.
format
Section titled formatType: ImageOutputFormat | undefined
You can optionally state the image file type output to be used.
By default, the <Image />
component will produce a .webp
file.
quality
Section titled qualityType: ImageQuality | undefined
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
to100
(interpreted differently between formats).
inferSize
Section titled inferSizeType: boolean
astro@4.4.0
Allows you to set the original width
and height
of a remote image automatically.
By default, this value is set to false
and you must manually specify both dimensions for your remote image.
Add inferSize
to the <Image />
component (or inferSize: true
to getImage()
) to infer these values from the image content when fetched. This is helpful if you don’t know the dimensions of the remote image, or if they might change:
inferSize
can fetch the dimensions of a remote image from a domain that has not been authorized, however the image itself will remain unprocessed.
<Picture />
Section titled <Picture />
Hinzugefügt in:
astro@3.3.0
Use the built-in <Picture />
Astro component to display a responsive image with multiple formats and/or sizes.
Picture properties
Section titled Picture properties<Picture />
accepts all the properties of the <Image />
component, plus the following:
formats
Section titled formatsType: ImageOutputFormat[]
An array of image formats to use for the <source>
tags. Entries will be added as <source>
elements in the order they are listed, and this order determines which format is displayed. For the best performance, list the most modern format first (e.g. webp
or avif
). By default, this is set to ['webp']
.
fallbackFormat
Section titled fallbackFormatType: ImageOutputFormat
Format to use as a fallback value for the <img>
tag. Defaults to .png
for static images (or .jpg
if the image is a JPG), .gif
for animated images, and .svg
for SVG files.
pictureAttributes
Section titled pictureAttributesType: HTMLAttributes<'picture'>
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.
getImage()
Section titled getImage()Type: (options: UnresolvedImageTransform) => Promise<GetImageResult>
getImage()
relies on server-only APIs and breaks the build when used on the client.
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 type:
inferRemoteSize()
Section titled inferRemoteSize()Type: (url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>
astro@4.12.0
A function to infer the dimensions of remote images. This can be used as an alternative to passing the inferSize
property.