Picture Component

Overview

The next-image-plus <Picture> is a primitive React component that extends the HTML <picture> element to provide features for automatic image optimization, using the power of the Next.js Image API and React 19.

next-image-plus provides 3 components for creating responsive images with art direction:

<Picture> component provides a wrapper for zero or more Source components and one Img component.
<Source> component specifies an image and a media query.
<Img> component provides a fallback image

A responsive image loads different sizes of the same image. The Next.js Image component handles this already.

A responsive image with Art Direction, will show different images for different display sizes, and takes it a step further, by loading completely different images depending on the display.

The next-image-plus <Picture> component allows developers to provide multiple different images for different display sizes.

The browser uses the first <Source> component with a media query that returns true. If none of the media queries match, the browser falls back to loading the image specified by the <Img> component.

Basic example:

import { Picture, Source, Img } from "next-image-plus";

export default function Page() {
  return (
    <Picture preload={true} fallbackMedia="(max-width: 430px)">
      <Source
        media="(min-width: 431px) and (max-width: 1023px)"
        src="/images/medium.jpg"
        width={860}
        height={430}
      />
      <Source
        media="(min-width: 1024px)"
        src="/images/large.jpg"
        width={220}
        height={220}
      />
      <Img
        src="/images/fallback.jpg"
        width={430}
        height={215}
        alt="mountains"
      />
    </Picture>
  );
}

Picture Props

Prop	Example	Type	Status
preload	`preload={true}`	Boolean	-
fallbackMedia	`fallbackMedia="(max-width: 430px)"`	String	-

preload

preload={false} // {false} | {true}

Optional prop for preloading the image. This works similar to the priority prop on the Next.js image. Should be used for any <Picture> component that is above the fold, and flagged as the Largest Contentful Paint (LCP).

For preloading to work properly, media queries cannot overlap. This is not a limitation of the component per se, but how browser's parse <link rel="preload"> elements in <head>. Media queries on <link rel="preload"> do not function the way they do on HTML elements.

The user agent will look at multiple <link rel="preload"> elements and find multiple matches if there is any overlap in the media queries. This can lead to performance issues, where multiple images are preloaded, so when setting media queries, make sure each one targets a unique range.

i.e, for your medium breakpoint, if your fallback is max-width: 430px

don't do this ~~(min-width: 430px) and (max-width: 1023px)~~

do this (min-width: 431px) and (max-width: 1023px)

fallbackMedia

An optional prop, to set the fallback media query for preloading.

Source Props

Prop	Example	Type	Status
src	`src="/image.jpg"`	String	Required
media	`media="(max-width: 430px)"`	String	Required
width	`width={500}`	Integer (px)	Required
height	`height={500}`	Integer (px)	Required
sizes	`sizes="(max-width: 768px) 100vw, 33vw"`	String	-

src

The value must a path string or a statically imported file.

// Path string example
<Source src="/image.jpg" />

// Static import example
import myImage from './image.jpg'

<Source src={myImage} />

A key difference between the native html element for <source> and the <Source> component, is the html element does not accept a src attribute, but uses srcset instead.

The value for srcset will get automatically generated for you, using the Next.js Image API, based on the src prop value.

media

A media query string, defining when to use this particular source image.

width

The width prop functions the same way as it does on the Next.js <Image> component:

The width property represents the intrinsic image width in pixels. This property is used to infer the correct aspect ratio of the image and avoid layout shift during loading. It does not determine the rendered size of the image, which is controlled by CSS, similar to the width attribute in the HTML <img> tag.

[ Source: Next.js Image API Reference ]

height

The height prop functions the same way as it does on the Next.js <Image> component:

The height property represents the intrinsic image height in pixels. This property is used to infer the correct aspect ratio of the image and avoid layout shift during loading. It does not determine the rendered size of the image, which is controlled by CSS, similar to the height attribute in the HTML <img> tag.

[ Source: Next.js Image API Reference ]

sizes

The sizes prop functions the same way as it does on the Next.js <Image> component:

Img Props

Prop	Example	Type	Status
src	`src="/image.jpg"`	String	Required
width	`width={500}`	Integer (px)	Required
height	`height={500}`	Integer (px)	Required
alt	`mountains and a river`	String	-

src