Skip to main content

Using Imgwire with <picture>

Use the HTML <picture> element with Imgwire when one image slot needs different crops, dimensions, or explicit format fallbacks across breakpoints.

For most browser-facing images, format=auto is the simpler default because Imgwire can choose a browser-friendly output from one URL. Reach for <picture> when the markup itself needs to decide which source to load.

When to use <picture>​

Use <picture> when you need:

  • A wide crop on desktop and a tighter crop on mobile.
  • Explicit AVIF, WebP, and JPEG fallback sources.
  • Different image content for different media queries.
  • A static HTML pattern that does not rely on a React component.

Use a normal <img> with format=auto when the same composition works everywhere:

<img
  src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=auto&quality=auto"
  width="960"
  height="540"
  alt="Product dashboard"
/>

Build an art-directed image​

Start with the Imgwire image ID you stored after upload. Then create delivery URLs for each layout slot. This example uses a wide crop for desktop and a square crop for smaller screens.

<picture>
  <source
    media="(min-width: 900px)"
    srcset="
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1200&height=675&resizing_type=cover&gravity=attention&format=auto&quality=auto  1200w,
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1800&height=1013&resizing_type=cover&gravity=attention&format=auto&quality=auto 1800w
    "
    sizes="min(100vw, 1200px)"
  />
  <source
    media="(max-width: 899px)"
    srcset="
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=480&height=480&resizing_type=cover&gravity=attention&format=auto&quality=auto 480w,
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=720&height=720&resizing_type=cover&gravity=attention&format=auto&quality=auto 720w
    "
    sizes="100vw"
  />
  <img
    src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&height=540&resizing_type=cover&gravity=attention&format=auto&quality=auto"
    width="960"
    height="540"
    alt="Product dashboard"
    loading="lazy"
    decoding="async"
  />
</picture>

The browser evaluates <source> elements from top to bottom. The first matching media query wins, and the browser then chooses the best srcset candidate for the current viewport and pixel density.

Add explicit format fallbacks​

If you need strict format fallback markup, create a source per format. Keep the transformation intent the same so each format represents the same visual variant.

<picture>
  <source
    type="image/avif"
    srcset="
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&format=avif&quality=auto 640w,
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=avif&quality=auto 960w
    "
    sizes="(max-width: 700px) 100vw, 640px"
  />
  <source
    type="image/webp"
    srcset="
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&format=webp&quality=auto 640w,
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=webp&quality=auto 960w
    "
    sizes="(max-width: 700px) 100vw, 640px"
  />
  <img
    src="https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&format=jpeg&quality=85"
    srcset="
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=640&format=jpeg&quality=85 640w,
      https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=960&format=jpeg&quality=85 960w
    "
    sizes="(max-width: 700px) 100vw, 640px"
    width="640"
    height="360"
    alt="Uploaded product image"
    loading="lazy"
  />
</picture>

This is useful for strict compatibility workflows. If you do not need to control the fallback chain yourself, prefer format=auto and let Imgwire negotiate the output format from the request headers.

Generate URLs with the SDK​

When your page is generated by JavaScript, use the SDK URL helper instead of hand-building query strings.

const desktopUrl = image.url({
  width: 1200,
  height: 675,
  resizing_type: 'cover',
  gravity: 'attention',
  format: 'auto',
  quality: 'auto',
});

const mobileUrl = image.url({
  width: 720,
  height: 720,
  resizing_type: 'cover',
  gravity: 'attention',
  format: 'auto',
  quality: 'auto',
});

The SDK keeps transformation parameter names consistent and produces canonical Imgwire delivery URLs.

Best practices​

  • Keep each <source> visually equivalent unless you are intentionally doing art direction.
  • Set width, height, or CSS aspect-ratio on the fallback <img> to avoid layout shift.
  • Use format=auto&quality=auto unless you have a specific fallback or export requirement.
  • Use gravity=attention for variable user-generated images where the subject may not be centered.
  • Keep candidate widths limited to real layout needs so the browser does not choose unnecessarily large files.

Last updated at: May 8, 2026