Skip to content
Astro Image Processor

Art Directive

Elements of the artDirectives property array in the <Picture> and <Background> components.

Generates <source> elements or elements within image-set() that are part of the output of the parent component.

Properties

src

Sets the image to use.

  • Type: string
  • Required
  • Remote file
    • Considered a remote file if it starts with http.
  • Data URL
    • Considered a Data URL if it starts with data:.
  • Local file
    • If it starts with /@fs, replace /@fs/ with file:// and process the new URL(src).pathname.
    • If it starts with /${assetsDirName}/, treat it as a root-relative path from outDir.
    • Otherwise, treat it as a root-relative path from rootDir.
  • Recommended to specify as a root-relative path from the project root (rootDir) (e.g., /src/assets/images/image.png).
    • You can also specify it in the form of an imported image with src={importedImage.src}, but this is not recommended due to double caching with this integration and astro:assets.

width

The value of the width attribute of the <source> element.

  • Type: number
  • When using densities, the value is interpreted as corresponding to 1x.
  • Note that not setting this can lead to “behavior that is technically correct but contrary to user expectations”.

height

The value of the height attribute of the <source> element.

  • Type: number

densities

Sets the x descriptors used in the srcset attribute of the <source> element.

  • Type: number[]
  • Example: [1, 2, 3]
  • If width is not set, the original size of the image is interpreted as the maximum scale.

widths

Sets the w descriptors used in the srcset attribute of the <source> element.

  • Type: number[]
  • Example: [1000, 2000, 3000]

sizes

Sets the sizes attribute of the <source> element.

  • Type: string | (resolvedWidths: number[], resolvedDensities: number[]) => string
  • Default: Inherit from the <img> element
  • Reference: sizes (MDN)
  • resolvedWidths will be the final resolved variations of image widths.
    • Even if densities is used, it will be the width value.

media

Sets the media attribute of the <source> element

placeholder

Selects the type of the placeholder.

  • Type: "blurred" | "dominantColor" | null
  • Default: blurred
  • blurred
    • Uses the image processed by the sharp instance specified in blurProcessor.
    • The image is converted to Base64 and directly written in CSS as a Data URL.
    • By default, “resized to 20px width and compressed with the lowest quality WebP” is used.
  • dominantColor
    • Uses a single color.
    • By default, uses the color obtained from sharp’s stats().dominant.
    • If the placeholderColor property is set, uses the color specified by the placeholderColor property.

placeholderColor

Sets the color to use when placeholder is dominantColor.

  • Type: string
  • Example: "#333", "hsl(150, 30%, 60%)", "var(--some-color)"
  • If this is not set, sharp().stats().dominant is used.
  • Reference: color (MDN)

blurProcessor

Sharp instance used to generate the blurred placeholder image.

  • Type: Sharp
  • Default: sharp().resize(20).webp({ quality: 1 })

upscale

Selects how to handle image upscaling required by densities or widths.

  • Type: "never" | "always" | "original"
  • Default: never
  • never: Ignore upscaling requests.
  • always: Upscale if required.
  • original: Ignore upscaling requests and add the original size of the image.

objectFit

Selects the CSS property object-fit for the <img> element.

  • Type: "fill" | "contain" | "cover" | "none" | "scale-down"
  • Apply through scoped CSS.
  • If placeholder is set to blurred, applies to the placeholder using background-size.
    • scale-down falls back to contain.

objectPosition

Selects the CSS property object-position for the <img> element.

  • Type: string
  • Apply through scoped CSS.
  • If placeholder is set to blurred, applies to the placeholder using background-position.

backgroundSize

Selects the CSS property background-size for the placeholder.

  • Type: "cover" | "contain" | "auto" | string | null
  • Reference: background-size (MDN)
  • Used if placeholder is blurred.
  • If backgroundSize is not set and objectFit is set, the value of objectFit に準じた値が使用される
  • Apply through scoped CSS.

backgroundPosition

Sets the CSS property background-position for the placeholder.

  • Type: string | null
  • Reference: background-position (MDN)
  • Used if placeholder is blurred.
  • If backgroundPosition is not set and objectPosition is set, the value according to objectFit is used.
  • Both backgroundPosition and objectPosition are not set, 50% 50% is used.
    • It is the default value of object-position.
  • Apply through scoped CSS.

enforceAspectRatio

Applies the CSS property aspect-ratio to the <picture> and <img> elements.

  • Type: boolean
  • Default: false
  • Sets the CSS property aspect-ratio to ${width} / ${height} based on the final resolved width and height values of the <source> element.
  • Apply through scoped CSS.

preload

Generates a <link rel="preload"> for the specified image format and adds it to the <head> element.

  • Type: "jpeg" | "png" | "avif" | "webp" | "gif"
  • Due to CSS specifications, multiple formats cannot be specified.

processor

Sharp instance used for image editing.

  • Type: Sharp | Sharp[]

profile

Assigns an individual identifier name as a string for the image editing content.

  • Type: string

formats

Selects the output formats.

  • Type: ("jpeg" | "png" | "avif" | "webp" | "gif")[]
  • Default: ["avif", "webp"]

formatOptions

Settings for the output formats.

  • Type: { jpeg: JpegOptions, png: PngOptions, webp: WebpOptions, avif: AvifOptions, gif: GifOptions } (sharp)
  • Default: sharp standard settings

minAge

Minimum cache duration for remote files (milliseconds).

  • Type: number
  • Overrides the specification in HTTP headers.

maxAge

Maximum cache duration for remote files (milliseconds).

  • Type: number
  • Overrides the specification in HTTP headers.