Picture Component

Overview

The next-image-plus <Picture /> component 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";

<Picture preload={true}>
  <Source
    media="(min-width: 430px) and (max-width: 1024px)"
    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 and a river"
  />
</Picture>

Picture Props

Prop	Example	Type	Status
preload	`preload={false}`	`boolean`	-
fallbackMedia	`fallbackMedia = "(max-width: 430px)";`	`string`	-
normalizeMediaQueries	`normalizeMediaQueries={false}`	`boolean`	-
children	`<Picture> <Source srcSet="image-320w.jpg" media="(max-width: 320px)" /> <Img src="image.jpg" alt="Example image" /> </Picture>`	`React.ReactElement<SourceProps, string \| React.JSXElementConstructor<any>>[] \| React.ReactElement<ImgProps, string \| React.JSXElementConstructor<any>>`	-

preload

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

preload={false}

Important

For preloading to work properly, media queries on <link rel="preload"> elements cannot overlap.

Media queries on <link rel="preload"> elements do not function the way they do on HTML elements. The user agent will look at multiple <link rel="preload"> media queries and find multiple matches if there is any overlap in the media queries. This can lead to performance issues, where multiple images are preloaded.

To avoid this, the <Picture /> component will automatically adjust the media queries set on Source to remove any overlap, by adding or subtracting 1 px. If this functionality causes any issues, it can be disabled with the normalizeMediaQueries prop.

fallbackMedia

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

fallbackMedia = "(max-width: 430px)";

normalizeMediaQueries

An optional prop to disable the component from normalizing the media queries to remove overlap.

normalizeMediaQueries={false}

children

Prop for passing the <Source /> and <Img /> components.

<Picture>
  <Source srcSet="image-320w.jpg" media="(max-width: 320px)" />
  <Img src="image.jpg" alt="Example image" />
</Picture>

Source Props

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

src

The URL of the image source. The value must be a path string or a statically imported file.

src = "/image.jpg"

Info

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.

media = "(max-width: 430px)"

width

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

width = {500}

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.

height = {500}

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 width attribute in the HTML <img> tag.

Source: Next.js Image API Reference

sizes

Optional prop to define the sizes of the image at different breakpoints. Used to determined the best size for the generated srcset. The sizes prop functions the same way as it does on the Next.js <Image /> component.

sizes="(max-width: 768px) 100vw, 33vw"

Source: Next.js Image API Reference

Img Props

Prop	Example	Type	Status
src	`src = "/image.jpg"`	`string`	Required
alt	`alt = "Mountains and a river"`	`string`	Required
width	`width = {500}`	`number`	Required
height	`height = {500}`	`number`	Required
media	`media = "(max-width: 430px)"`	`string`	-

src

The URL of the image source. The value must a path string or a statically imported file.

src = "/image.jpg"

alt

The alt text for the image.

alt = "Mountains and a river"

width

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

width = {500}

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.

height = {500}

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 width attribute in the HTML <img> tag.

Source: Next.js Image API Reference

media

Optional media query to be used for the fallback image, if preload is true.

media = "(max-width: 430px)"

Getting Started

Background Image Component