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

• Type: string
• Required
• source (MDN)

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.