Skip to main content

Responsive image variants using srcset

Responsive image markup lets the browser choose an Imgwire variant that matches the user's viewport instead of downloading one oversized image everywhere.

This tutorial shows the plain HTML pattern and the React <ResponsiveImage /> component from @imgwire/react.

Choose your layout slot​

Start with the rendered width of the image in your layout. For example, a content image might be full width on small screens and capped at 720 CSS pixels on larger screens.

<img
  src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=720&format=auto&quality=auto"
  srcset="
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=360&format=auto&quality=auto   360w,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=720&format=auto&quality=auto   720w,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1080&format=auto&quality=auto 1080w,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1440&format=auto&quality=auto 1440w
  "
  sizes="(max-width: 760px) 100vw, 720px"
  width="720"
  height="405"
  alt="Uploaded image preview"
  loading="lazy"
  decoding="async"
/>

The srcset tells the browser which Imgwire widths are available. The sizes attribute tells the browser how large the image will render in CSS pixels.

Use fixed aspect ratio variants​

For cards, feeds, and grids, request both width and height with resizing_type=cover. Add gravity=attention when uploaded content has variable composition.

<img
  src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&height=360&resizing_type=cover&gravity=attention&format=auto&quality=auto"
  srcset="
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=320&height=180&resizing_type=cover&gravity=attention&format=auto&quality=auto 320w,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&height=360&resizing_type=cover&gravity=attention&format=auto&quality=auto 640w,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&height=540&resizing_type=cover&gravity=attention&format=auto&quality=auto 960w
  "
  sizes="(max-width: 720px) 100vw, 33vw"
  width="640"
  height="360"
  alt="Gallery card image"
/>

This keeps repeated UI cards stable while still allowing the browser to choose an appropriately sized image.

Use ResponsiveImage in React​

Install the React SDK if your app uses React:

yarn add @imgwire/react @imgwire/js

Wrap your app once with ImgwireProvider:

import { ImgwireProvider } from '@imgwire/react';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <ImgwireProvider
      config={{
        apiKey: import.meta.env.VITE_IMGWIRE_CLIENT_KEY,
      }}
    >
      {children}
    </ImgwireProvider>
  );
}

Then render the responsive image:

import { ResponsiveImage } from '@imgwire/react';

export function GalleryImage({ imageId }: { imageId: string }) {
  return (
    <ResponsiveImage
      id={imageId}
      alt="Gallery image"
      format="auto"
      quality="auto"
      breakpoints={{
        sm: { minWidth: 0, width: 360 },
        md: { minWidth: 640, width: 720 },
        lg: { minWidth: 1024, width: 1080 },
      }}
    />
  );
}

For fixed-ratio cards, include the same crop behavior in each breakpoint:

<ResponsiveImage
  id={imageId}
  alt="Gallery card"
  format="auto"
  quality="auto"
  breakpoints={{
    sm: {
      minWidth: 0,
      width: 320,
      height: 180,
      crop: '320:180:attention',
    },
    md: {
      minWidth: 640,
      width: 640,
      height: 360,
      crop: '640:360:attention',
    },
    lg: {
      minWidth: 1024,
      width: 960,
      height: 540,
      crop: '960:540:attention',
    },
  }}
/>

Use DPR for fixed CSS slots​

Use width descriptors (360w, 720w) for fluid responsive layouts. Use DPR descriptors (1x, 2x) when the image renders at one fixed CSS size.

<img
  src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=400&dpr=1&format=auto&quality=auto"
  srcset="
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=400&dpr=1&format=auto&quality=auto 1x,
    https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=400&dpr=2&format=auto&quality=auto 2x
  "
  width="400"
  height="225"
  alt="Fixed-width product card"
/>

Best practices​

  • Match candidate widths to real layout sizes.
  • Keep sizes accurate; the browser uses it before downloading the image.
  • Use format=auto&quality=auto for public browser delivery.
  • Reserve layout space with width, height, or aspect-ratio.
  • Use gravity=attention or an explicit crop when the important region should stay visible.

Last updated at: May 8, 2026