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,
    },
  ]}
/>

Background Image Props

Prop	Example	Type	Status
id	`id="examples__background-image"`	`string`	Required
as	`as="span"`	`React.ElementType<any, keyof React.JSX.IntrinsicElements>`	-
preload	`preload={false} // {false} \| {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`	-
children	`<BackgroundImage> <div>content</div> </BackgroundImage>`	`React.ReactNode`	-
normalizeMediaQueries	`normalizeMediaQueries={false} // {false} \| {true}`	`boolean`	-

id

A unique id for the background image html element.

id="examples__background-image"

as

The HTML tag or React component to use as the wrapper. Defaults to <div>.

as="span"

preload

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).

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

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.

images={[ ... ]}

className

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

className="absolute inset-0 bg-cover bg-center bg-no-repeat"

style

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

style={{ color: "red" }}

children

Optional child elements to render inside the component.

<BackgroundImage>
  <div>content</div>
</BackgroundImage>

normalizeMediaQueries

Optional prop to disable the component from normalizing the media queries to remove overlaps. Defaults to true

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

Background Image Options

Prop	Example	Type	Status
breakpoint	`breakpoint = "fallback"`	`string`	-
media	`media = (max-width: 430px)`	`string`	-
url	`url = "https://picsum.photos/id/870/430/466"`	`string`	Required
width	`width = 430`	`number`	Required
height	`height = 430`	`number`	Required

breakpoint

Optional breakpoint name.

breakpoint = "fallback"

media

The media query for the breakpoint.

media = (max-width: 430px)

url

The url for the background image.

url = "https://picsum.photos/id/870/430/466"

width

The width of the background image.

width = 430

height

The height of the background image.

height = 430

Picture Component

Examples: Picture