Background Image Component

Overview

The next-image-plus <BackgroundImage /> component is a primitive React component that extends any HTML element, to add a background image, using the power of the Next.js Image API and React 19.

The component does not provide any styles and is fully compatible with any React styling framework.

It can handle a single image, or be used for responsive background images. The correct background-image url based on the image options passed to images prop will be automatically rendered.

Basic usage:

import { BackgroundImage } from "next-image-plus";

<BackgroundImage
  id="examples__background-image"
  images={[
    {
      url: "https://picsum.photos/id/870/430/466",
      width: 430,
      height: 466,
    },
  ]}
>

Advanced usage: Responsive Background Image

import { BackgroundImage } from "next-image-plus";

<BackgroundImage
  id="examples__background-image-responsive"
  className="absolute inset-0 bg-cover bg-center bg-no-repeat"
  preload={true}
  images={[
    {
      media: "(max-width: 430px)",
      url: "https://picsum.photos/id/870/430/466",
      width: 430,
      height: 466,
    },
    {
      media: "(min-width: 430px) and (max-width: 768px)",
      url: "https://picsum.photos/id/870/768/512",
      width: 768,
      height: 512,
    },
    {
      media: "(min-width: 768px)",
      url: "https://picsum.photos/id/870/2560/800",
      width: 2560,
      height: 800,
    },
  ]}
/>

Props

Prop	Example	Type	Status
id	`id="examples__background-image"`	String	Required
as	`as="span"`	React.ElementType	-
preload	`preload={true}`	Boolean	-
images	`images={[ ... ]}`	BackgroundImageOptions[]	Required
className	`className="absolute inset-0 bg-cover bg-center bg-no-repeat"`	String	-
style	`style={{ color: "red" }}`	React.CSSProperties	-
normalizeMediaQueries	`normalizeMediaQueries={false}`	Boolean	-

id

A unique id for the background image html element.

as

An optional prop to control the HTML element used. The component will default to using a <div> element.

preload

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

Optional prop for preloading the background image. This works similar to the priority prop on the Next.js image.

Should be used for any <BackgroundImage /> component that is above the fold, and flagged as the Largest Contentful Paint (LCP).

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 <BackgroundImage /> component will automatically adjust the media queries set on the preload links, by adding or subtracting 1 px. If this functionality causes any issues, it can be disabled with the normalizeMediaQueries prop.

images

An array of image objects of the BackgroundImageOptions type.

BackgroundImageOptions Type

Property	Description	Example	Type	Status
breakpoint	Optional breakpoint name	`fallback`	string	-
media	The media query for the breakpoint	`(max-width: 430px)`	string	-
url	The url for the background image	`"https://picsum.photos/id/870/430/466"`	string	Required
width	The width of the background image	`430`	number	Required
height	The height of the background image	`466`	number	Required

className

Optional prop for any CSS class name(s) for the background image element.

style

Optional prop for any CSS style properties for the background image element.

normalizeMediaQueries

normalizeMediaQueries={false} // {false} | {true}

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

Picture Component

Examples: Picture