<Picture />

The <Picture /> component is an Astro component that renders an optimized and responsive <picture /> element. This component supports all the features that Astro ImageTools has to offer for regular images. It’s perfect for advanced use cases where you need to offer multiple source formats, need Art Direction, and the onload fade-in transition. It’s the component that you may want to use most of the times.

Code Example

---
import { Picture } from "astro-imagetools/components";
---

<Picture
  src="/src/images/landscape.jpg"
  alt="A landscape image"
  artDirectives={[
    {
      src: "/src/images/portrait.jpg",
      media: "(orientation: potrait)",
    },
  ]}
/>

Component Props

Below is the list of props that the <Picture /> component accepts. Only the src and alt props are required.

`src`

Type: string

Default: undefined

The path to the source image. If local, the path must be relative to the project root. Remote URLs and Data URIs are also supported.

Code example:

<!-- Local Image -->
<Picture
  src="/src/images/image.jpg"
  alt="A local image"
/>

<!-- Remote URL -->
<Picture
  src="https://example.com/image.jpg"
  alt="A remote image"
/>

<!-- Data URI -->
<Picture
  src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  alt="A base64 encoded image"
/>

SSR Usage

In SSR mode, if you are using local images, you have to generate assets for them first and then you have to pass the path to the assets to the src property.

---
import src from "../path/to/source_image.jpg";
---

<Picture
  src={src}
  alt="A local image in SSR mode"
/>

The raw query parameter has been used to tell the internal Vite plugin to emit the asset from the source image unchanged.

`alt`

Type: string

Default: undefined

The alternative text to display if the image fails to load.

Code example:

<Picture
  src="https://mdn.github.io/learning-area/html/multimedia-and-embedding/responsive-images/elva-800w.jpg"
  alt="A father holiding his beloved daughter in his arms"
/>

`sizes`

Type: string or (breakpoints: number[]) => string

Default: (breakpoints) => `(min-width: ${breakpoints[breakpopints.length - 1]}px) ${breakpoints[breakpopints.length - 1]}px, 100vw

A string or function that returns a string suitable for the value of the sizes attribute of the generated <img /> element. The final calculated breakpoints are passed to the function as a parameter.

Code example:

<!-- string type -->
<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  sizes="(min-width: 1024px) 1024px, 100vw"
/>

<!-- function type -->
<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  sizes={(breakpoints) => {
    const maxWidth = breakpoints[breakpoints.length - 1];
    return `(min-width: ${maxWidth}px) ${maxWidth}px, 100vw`;
  }}
/>

`preload`

Default: undefined

Which format of image set to preload.

Note: It’s not reasonable to preload multiple formats of the same image. And due to the factors like file size and browser support, it’s not possible to pick the best format automatically.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  preload="webp"
/>

`loading`

Type: "lazy" | "eager" | "auto" | null

Default: preload ? "eager" : "lazy"

The value of the loading attribute of the generated <img /> element. If null is provided, the loading attribute will be omitted.

Code Example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  loading="lazy"
/>

`decoding`

Type: "async" | "sync" | "auto" | null

Default: "async"

The value of the decoding attribute of the generated <img /> element. If null is provided, the decoding attribute will be omitted.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  decoding="async"
/>

`attributes`

Type:

declare interface Attributes {
  picture?: Record<any, any>;
  style?: Record<any, any>;
  link?: Omit<Record<any, any>, "as" | "rel" | "imagesizes" | "imagesrcset">;
  img?: Omit<
    Record<any, any>,
    | "src"
    | "alt"
    | "srcset"
    | "sizes"
    | "width"
    | "height"
    | "loading"
    | "decoding"
  >;
}

Default: {}

The HTML attributes to add to the generate elements. If the class, style, and onload attributes are present, the values passed via this config will be merged.

Code Example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  attributes={{
    link: {
      fetchpriority: "high"
    }
  }}
/>

`layout`

Type: "constrained" | "fixed" | "fullWidth" | "fill"

Default: "constrained"

The layout mode to determine the resizing behavior of the image in the browser.

In constrained mode, the image will occupy full width of the container with max-width set to 100% its width. The height of the image will be calculated based on the aspect ratio of the image. The image will be scaled down to fit the container but won’t be enlarged.

In fixed mode, the image will have a fixed width and height. The width and height props will be used to set the width and height of the image. The image won’t be scaled down nor enlarged.

In fullWidth mode, the image will be scaled up or down to occupy the full width of the container. The height of the image will be calculated based on the aspect ratio of the image.

In fill mode, the image will be scaled up or down to fill the entire width and height of the container.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  layout="constrained"
/>

`placeholder`

Type: "dominantColor" | "blurred" | "tracedSVG" | "none"

Default: "blurred"

The placeholder to be displayed while the image is loading.

If placeholder is set to "dominantColor", the dominant color of the source image will be used as the placeholder.

If the value is set to "blurred", a very low-resolution version of the provided image will be enlarged and used as the placeholder.

If the value is set to "tracedSVG", a traced SVG of the image will be used as the placeholder. If the value is set to "none", no placeholder will be displayed.

Note: If the value is set to "tracedSVG", the placeholder can be customized to be a Posterized SVG too. See the formatOptions prop for more details.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  placeholder="blurred"
/>

`breakpoints`

Type: number[] | { count?: number; minWidth?: number; maxWidth?: number }

Default: undefined

An array of widths in pixels to generate image sets for. If not provided, the breakpoints will be calculated automatically.

If an object is passed then the breakpoints will be calculated automatically based on the values of the count, minWidth, and maxWidth properties. The count property is to specify the number of breakpoints to generate. The minWidth and maxWidth properties are to specify the widths to generate in the range between their values.

When an object is passed or the breakpoints prop is not provided, the breakpoints are calculated using a simple formula/algorithm. Instead of explaining the complete algorithm here, I am linking to the code.

Code example:

<!-- number[] type -->
<Picture
  src="https://picsum.photos/1600/900"
  alt="A random image"
  breakpoints={[200, 400, 800, 1600]}
/>

<!-- { count?: number; minWidth?: number; maxWidth?: number } type -->
<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  breakpoints={{ count: 3, minWidth: 300, maxWidth: 1024 }}
  /* three breakpoints will be generated ranging from 300px to 1024px */
/>

`objectFit`

Type: "fill" | "contain" | "cover" | "none" | "scale-down"

Default: cover

The value of the object-fit CSS property of the generated <img /> element.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  objectFit="cover"
/>

`objectPosition`

Type: string

Default: 50% 50%

The value of the object-position CSS property of the generated <img /> element.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  objectPosition="50% 50%"
/>

`format`

Type: format | format[] | [] | null format: "heic" | "heif" | "avif" | "jpg" | "jpeg" | "png" | "tiff" | "webp" | "gif" Default: ["avif", "webp"] The image format or formats to generate image sets for. If format is set to null or [], no additional image set will be generated. > Note: Passing [] or null does not necessarily mean that no image sets will be generated. Image sets will still be generated for the source format if includeSourceFormat is set to true (which is the default value) and for the format specified in the fallbackFormat prop (the default value is the source format).

Code Example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  format={["avif", "webp"]}
/>

`fallbackFormat`

Type: format

Default: The format of the source image

The format the browser will fallback to if the other formats are not supported.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  format={["webp", "jpg"]}
  fallbackFormat="png"
/>

`includeSourceFormat`

Type: boolean

Default: true

Whether to generate image set for the source format or not.

Code example:

<Picture
  src="/src/images/image.tiff"
  alt="A random image"
  fallbackFormat="png"
  includeSourceFormat={false}
/>

`formatOptions`

Type

formatOptions is an object that takes config options for all the supported formats: heic, heif, avif, jpg, jpeg, png, tiff, webp, gif, and tracedSVG.

The supported config options of all the formats except tracedSVG are: flip, flop, invert, flatten, normalize, grayscale, hue, saturation, brightness, width, height, aspect, background, tint, blur, median, rotate, quality, fit, kernel, position.

The config options supported by the tracedSVG format are listed below.

Default: The default values for the all the formats except tracedSVG are inherited from the direct configs of the {}. And for more information on the tracedSVG property, see the PotraceOptions interface.

The configuration options for the different formats. These configuration options will be respected when generating image sets for different formats.

The tracedSVG config object is used only when the placeholder prop is set to "tracedSVG".

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  placeholder="tracedSVG"
  format={["webp", "jpg"]}
  fallbackFormat="png"
  includeSourceFormat={false}
  formatOptions={{
    jpg: {
      quality: 80,
    },
    png: {
      quality: 80,
    },
    webp: {
      quality: 50,
    },
    tracedSVG: {
      options: {
        background: "#fff",
        color: "#000",
        turnPolicy: "black",
        turdSize: 1,
        alphaMax: 1,
        optCurve: true,
        threshold: 100,
        blackOnWhite: false,
      },
    },
  }}
/>

`tracedSVG`

All the properties of the tracedSVG property are the configuration options supported by the node-potrace library. These options are used to generate traced SVGs when the placeholder prop is set to "tracedSVG". All the properties defined below are optional.

Note: Most of the below jargons are taken from the potrace documentation. I have tried my best to simplify the config options and make the documentation as simple and clear as possible.

If you want to go deeper into this, check the Technical documentation of the original C potrace library.

If you have a good knowledge on the potrace library and about bitmap tracing and posterizing, please consider contributing to update the documentation of this section.

`function`

Type: "trace" | "posterize"

Default: "trace"

Which method of the node-potrace library to use. The posterize method is basically tracing the image multiple times to produce a more accurate result. See this example for more information.

`options`

`turnPolicy`

Default: "minority"

How to resolve ambiguities in path decomposition. Refer to the potrace-algorithm documentaion (PDF, page 4) for more information.

`turdSize`

Type: number

Default: 2

Suppress speckles of up to this size.

`alphaMax`

Type: number

Default: 1

Corner threshold parameter.

`optCurve`

Type: boolean

Default: true

Curve optimization.

`optTolerance`

Type: number

Default: 0.2

Curve optimization tolerance.

`threshold`

Type: number

Default: -1

When function is "trace" :

Threshold below which color is considered black. Should be a number between 0 and 255 or -1 in which case threshold will be selected automatically using Algorithm For Multilevel Thresholding.

When function is "posterize" :

Breaks image into foreground and background (and only foreground being broken into desired number of layers). Basically when provided it becomes a threshold for last (least opaque) layer and then steps - 1 intermediate thresholds calculated. If steps is an array of thresholds and every value from the array is lower (or larger if blackOnWhite parameter set to false) than threshold - threshold will be added to the array, otherwise just ignored.

`blackOnWhite`

Type: boolean

Default: true

Specifies colors by which side from threshold should be turned into vector shape.

`color`

Type: "auto" | string

Default: "auto"

Fill color for the traced image. If "auto" is provided, the color will be black or white depending on the blackOnWhite property.

`background`

Type: "transparent" | string

Default: "transparent"

Background color of the traced image. If "transparent" is provided, no background will be present.

`fill`

Type: "spread" | "dominant" | "median" | "mean"

Determines how fill color for each layer should be selected.

dominant - Most frequent color in range (used by default),
mean - Arithmetic mean (average),
median - Median color,
spread - Ignores color information of the image and just spreads colors equally in range between 0 and threshold (or threshold and ..255 if blackOnWhite is set to false).

Note: This option is available only when function is "posterize".

`ranges`

Type: "auto" | "equal"

How color stops for each layer should be selected. Ignored if steps is an array. Possible values are:

auto - Performs automatic thresholding (using Algorithm For Multilevel Thresholding). Preferable method for already posterized sources, but takes long time to calculate 5 or more thresholds (exponential time complexity) (used by default)
equal - Ignores color information of the image and breaks available color space into equal chunks

Note: This option is available only when function is "posterize".

`steps`

Type: number | number[]

Specifies desired number of layers in resulting image. If a number provided - thresholds for each layer will be automatically calculated according to ranges property. If an array provided it expected to be an array with precomputed thresholds for each layer (in range between 0 and 255).

Note: This option is available only when function is "posterize".

Code example:

---
const src = "https://picsum.photos/1024/768";
const alt = "A random image";
const placeholder = "tracedSVG";

const traceOptions = {
  background: "#fff",
  color: "#000",
  turnPolicy: "black",
  turdSize: 1,
  alphaMax: 1,
  optCurve: true,
  threshold: 100,
  blackOnWhite: false,
};

const posterizeOptions = {
  fill: "spread",
  steps: [0, 50, 100],
  ranges: "equal",
};
---

<Picture
  src={src}
  alt={alt}
  placeholder={placeholder}
  /* tracing SVG */
  formatOptions={{
    tracedSVG: {
      function: "trace",
      options: traceOptions,
    },
  }}
/>

<Picture
  src={src}
  alt={alt}
  placeholder={placeholder}
  /* posterizing SVG */
  formatOptions={{
    tracedSVG: {
      function: "posterize",
      options: {
      ...traceOptions,
      ...posterizeOptions,
      },
    },
  }}
/>

`fadeInTransition`

Type: boolean | { delay?: string; duration?: string; timingFunction?: string; }

Default: true | { delay: "0s"; duration?: "1s"; timingFunction: "ease"; }

Whether or not to fade in the image when it is loaded. If an object is passed with the delay, duration, and timingFunction properties, the values will be used as values for the transition-delay, transition-duration, and transition-timing-function CSS properties, respectively.

Note: This prop is only available when the placeholder prop of at least one source is not "none".

Code Example:

---
const src = "https://picsum.photos/1024/768";
const alt = "A random image";
---

<!-- boolean type -->
<Picture
  src={src}
  alt={alt}
  fadeInTransition={false}
/>

<!-- { delay: string; duration: string; timingFunction: string; } type -->
<Picture
  src={src}
  alt={alt}
  fadeInTransition={{
    delay: "0.5s",
    duration: "0.5s",
    timingFunction: "linear",
  }}
/>

`artDirectives`

Type: ArtDirective[]

An ArtDirective object can take all the props supported by the{” ”} {} except alt, preload, loading, decoding, attributes, layout, and fadeInTransition. The only addition is media. Only the src and media properties are required.

Default: undefined

The list of art directions to be applied to the generated picture.

Code Example:

<Picture
  src="/src/images/landscape.jpg"
  alt="alt text"
  artDirectives={[
    {
      media: "(max-aspect-ratio: 3/2)",
      src: "/src/images/portrait.jpg",
      breakpoints: [256, 384, 576],
      width: 768,
      height: 1024,
      format: ["avif"],
      fallbackFormat: "webp",
      includeSourceFormat: false,
    },
  ]}
/>

`media`

Type: string

Default: undefined

The CSS media query to use to define the art direction.

Code Example:

<Picture
  src="/src/image/landscape.jpg"
  alt="A landscape image"
  rotate={22.5}
  artDirectives={[
    {
      src: "/src/image/dark-potrait.jpg",
      media: "(prefers-color-scheme: dark) and (orientation: portrait)",
    },
    {
      src: "/src/image/light-potrait.jpg",
      media: "(prefers-color-scheme: light) and (orientation: portrait)",
    },
    {
      src: "/src/image/dark-landscape.jpg",
      media: "(prefers-color-scheme: dark) and (orientation: landscape)",
    },
  ]}
/>

`flip`

Type: boolean

Default: undefined

Flip the image about the vertical axis. This step is always performed after any rotation.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  flip={true}
/>

`flop`

Type: boolean

Default: undefined

Flop the image about the vertical axis. This step is always performed after any rotation.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  flop={true}
/>

`invert`

Type: boolean

Default: undefined

Produces a negative of the image.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  invert={true}
/>

`flatten`

Type: boolean

Default: undefined

Whether to remove the alpha channel of the image or not, reducing filesize. Transparent pixels will be merged with the color set by background.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  flatten={true}
/>

`normalize`

Type: boolean

Default: undefined

Normalizes the image by stretching its luminance to cover the full dynamic range. This Enhances the output image contrast.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  normalize={true}
/>

`grayscale`

Type: boolean

Default: undefined

Converts the image to an 8-bit grayscale image.

Note: If true the image will be converted to the b-w colorspace, meaning the resulting image will only have one channel.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  grayscale={true}
/>

`hue`

Type: number

Default: undefined

Adjusts the images hue rotation by the given number of degrees. Commonly used together with saturation and brightness.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  hue={-30}
/>

`saturation`

Type: number

Default: undefined

Adjusts the images saturation with the given saturation multiplier. Commonly used together with hue and brightness.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  saturation={0.5}
/>

`brightness`

Type: number

Default: undefined

Adjusts the images brightness with the given brightness multiplier. Commonly used together with hue and saturation.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  brightness={0.5}
/>

`width` | `w`

Type: number

Default: The width of the source image

Resizes the image to be the specified amount of pixels wide. If not given the height will be scaled accordingly.

Note: The specified width will be used to resize the source image when loading it. The final widths of the image will be based on the final calculated breakpoints.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  width={1024}
/>

`height` | `h`

Type: number

Default: The height of the source image

Resizes the image to be the specified amount of pixels tall. If not given the width will be scaled accordingly.

Note: The specified height will be used to resize the source image when loading it. The final heights of the image will be based on the final calculated breakpoints.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  height={300}
/>

`aspect` | `ar`

Type: number

Default: The aspect ratio of the source image

Resizes the image to be the specified aspect ratio. If height and width are both provided, this will be ignored. If height is provided, the height will be scaled accordingly. If width is provided, the height will be scaled accordingly. If neither height nor width are provided, the image will be cropped to the given aspect ratio.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  aspect={1.3333333333333333}
/>

`background`

Type: string

Default: undefined

This instructs various props (e.g. rotate) to use the specified color when filling empty spots in the image.

Note: This prop does nothing on it’s own, it has to be used in conjunction with another prop.

Code example:

The below example demonstrates all the posible cases when the background prop is used.

---
const src = "https://picsum.photos/1024/768";
const alt = "A random image";
---

<Picture
  src={src}
  alt={alt}
  flatten={true}
  background="#FFFFFFAA"
/>

<Picture
  src={src}
  alt={alt}
  rotate={90}
  background="hsl(360, 100%, 50%)"
/>

<Picture
  src={src}
  alt={alt}
  width={800}
  height={450}
  fit="contain"
  background="crimson"
/>

`tint`

Type: string

Default: undefined

Tints the image using the provided chroma while preserving the image luminance. If the image has an alpha channel it will be untouched.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  tint="rgba(10,33,127)"
/>

`blur`

Type: string

Default: undefined

Blurs the image. If the value is true, it performs a fast blur. When a number between 0.3 and 1000 is provided, it performs a more accurate gaussian blur.

Code example:

---
const src = "https://picsum.photos/1024/768";
const alt = "A random image";
---

<Picture
  src={src}
  alt={alt}
  blur={true}
  /* A fast blur will be performed */
/>

<Picture
  src={src}
  alt={alt}
  blur={100}
  /* A more accurate blur will be performed */
/>

`median`

Type: number | boolean

Default: undefined

Applies a median filter. This is commonly used to remove noise from images.

Code example:

---
const src = "https://picsum.photos/1024/768";
const alt = "A random image";
---

<!-- boolean type -->
<Picture
  src={src}
  alt={alt}
  median={true}
/>

<!-- number type -->
<Picture
  src={src}
  alt={alt}
  median={50}
/>

`rotate`

Type: number

Default: undefined

Rotate the image by the specified number of degrees.

Note: The empty parts are filled with the color specified in the background prop.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  rotate={90}
/>

`quality`

Type: number

Default: undefined

All formats (except gif) allow the quality to be adjusted by setting this directive.

The argument must be a number between 0 and 100.

See sharps Output options for default quality values.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  quality={50}
/>

`fit`

Type: "cover" | "contain" | "fill" | "inside" | "outside"

Default: undefined

When both width and height are provided, this directive can be used to specify the method by which the image should fit.

Note: The empty parts are filled with the color specified in the background prop.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  width={800}
  height={450}
  fit="contain"
/>

`kernel`

Type: "nearest" | "cubic" | "mitchell" | "lanczos2" | "lanczos3"

Default: undefined

The interpolation kernel to use when resizing the images.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  kernel="lanczos3"
/>

`position`

Default: undefined

When both width and height are provided AND fit is is set to cover or contain, this directive can be used to set the position of the image.

See sharp’s resize options for more information.

Code example:

<Picture
  src="https://picsum.photos/1024/768"
  alt="A random image"
  width={800}
  height={450}
  fit="contain"
  position="attention"
/>

<Picture />

Code Example

Component Props

src

SSR Usage

alt

sizes

preload

loading

decoding

attributes

layout

placeholder

breakpoints

objectFit

objectPosition

format

fallbackFormat

includeSourceFormat

formatOptions

tracedSVG

function

options

turnPolicy

turdSize

alphaMax

optCurve

optTolerance

threshold

blackOnWhite

color

background

fill

ranges

steps

fadeInTransition

artDirectives

media

flip

flop

invert

flatten

normalize

grayscale

hue

saturation

brightness

width | w

height | h

aspect | ar

background

tint

blur

median

rotate

quality

fit

kernel

position

`src`

`alt`

`sizes`

`preload`

`loading`

`decoding`

`attributes`

`layout`

`placeholder`

`breakpoints`

`objectFit`

`objectPosition`

`format`

`fallbackFormat`

`includeSourceFormat`

`formatOptions`

`tracedSVG`

`function`

`options`

`turnPolicy`

`turdSize`

`alphaMax`

`optCurve`

`optTolerance`

`threshold`

`blackOnWhite`

`color`

`background`

`fill`

`ranges`

`steps`

`fadeInTransition`

`artDirectives`

`media`

`flip`

`flop`

`invert`

`flatten`

`normalize`

`grayscale`

`hue`

`saturation`

`brightness`

`width` | `w`

`height` | `h`

`aspect` | `ar`

`background`

`tint`

`blur`

`median`

`rotate`

`quality`

`fit`

`kernel`

`position`