What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
Tutorials
The `AgilityPic` component from `@agility/nextjs` provides a powerful, declarative way to render responsive images using the native HTML `<picture>` element combined with Agility CMS's image transformation API.
The AgilityPic component from @agility/nextjs provides a powerful, declarative way to render responsive images using the native HTML <picture> element combined with Agility CMS's image transformation API.
The Next.js <Image /> component performs image transformation compute on your web server, which has some drawbacks:
The AgilityPic component leverages Agility CMS's image transformation API, which:
format=autoFor optimal image quality across all devices, follow these guidelines:
Upload images at twice the maximum display width. DPI doesn't matter on the web; only pixel dimensions do (see Image Best Practices).
For example, if an image will display at a maximum of 600px wide:
AgilityPic component will serve appropriately sized versions to each deviceModern devices have pixel densities of 2x or higher. A 600px container on a Retina display actually renders 1200 physical pixels. By uploading at 2x, you ensure:
The simplest usage requires only an image and a fallback width:
import { AgilityPic } from "@agility/nextjs"
<AgilityPic
image={image}
fallbackWidth={400}
className="w-full h-auto rounded-2xl"
sources={[
{ media: "(min-width: 1024px)", width: 800 },
{ media: "(min-width: 640px)", width: 600 },
{ media: "(max-width: 639px)", width: 500 },
]}
/>
The fallbackWidth serves two purposes:
<picture>sources matchImportant: The fallbackWidth determines your Lighthouse/PageSpeed score. Mobile performance tools like Google Lighthouse use the fallback image when calculating page speed metrics. Keep fallbackWidth small (400-600px) to ensure optimal scores and fast load times for mobile users on slow networks (3G).
The sources array then provides appropriately sized images for users on larger screens, ensuring they get the best quality for their device without penalizing your mobile performance metrics.
For full responsive control, use the sources prop to define different image sizes for different viewport widths:
<AgilityPic
image={image}
fallbackWidth={400}
className="w-full h-full object-cover"
sources={[
{ media: "(min-width: 1280px)", width: 1200 },
{ media: "(min-width: 640px)", width: 800 },
{ media: "(max-width: 639px)", width: 640 },
]}
/>
The browser evaluates sources from top to bottom and uses the first match. This example:
For a hero that spans full width on desktop but needs a fast mobile fallback:
<AgilityPic
image={image}
fallbackWidth={600}
className="w-full h-auto rounded-2xl shadow-2xl"
sources={[
{ media: "(min-width: 1280px)", width: 1200 },
{ media: "(min-width: 768px)", width: 900 },
{ media: "(max-width: 767px)", width: 700 },
]}
/>
For a card that displays in different layouts:
<AgilityPic
image={post.image}
fallbackWidth={400}
className="absolute inset-0 w-full h-full object-cover"
sources={[
{ media: "(max-width: 639px)", width: 640, height: 360 },
{ media: "(max-width: 767px)", width: 800, height: 400 },
{ media: "(max-width: 1023px)", width: 1200, height: 600 },
{ media: "(min-width: 1024px)", width: 512, height: 512 },
]}
/>
Each entry sets height so the CDN crops to the focal point. See Handling Focal Points with Different Aspect Ratios.
For a full-width carousel with different sizes per breakpoint:
<AgilityPic
image={image}
className="w-full h-full object-cover"
fallbackWidth={400}
sources={[
{ media: "(min-width: 1280px)", width: 1200 },
{ media: "(min-width: 640px)", width: 800 },
{ media: "(max-width: 639px)", width: 640 },
]}
/>
When you need both width and height (for art-directed cropping):
<AgilityPic
image={backgroundImage}
alt={backgroundImage.label || "Background"}
fallbackWidth={1425}
sources={[
{
media: "(max-width: 640px)",
width: 640,
height: 224,
},
{
media: "(max-width: 1024px)",
width: 1024,
height: 400,
},
{
media: "(min-width: 1024px)",
width: 1425,
height: 800,
},
]}
className="h-56 w-full object-cover lg:h-full lg:w-1/2"
/>
For avatars and small images, keep sizes minimal:
<AgilityPic
image={author.headShot}
fallbackWidth={64}
className="size-12 rounded-full object-cover"
sources={[
{ media: "(min-width: 768px)", width: 96 },
{ media: "(max-width: 767px)", width: 64 },
]}
/>
For the best quality on high-DPI screens, you can provide multiple resolutions using srcSet syntax. This example serves 2x images to Retina displays:
import type { ImageField } from "@agility/nextjs"
interface Props {
image: ImageField
className?: string
}
export function RetinaImage({ image, className }: Props) {
const baseUrl = image.url
return (
<picture>
{/* Desktop: 600px display, serve 1200px for 2x screens */}
<source
media="(min-width: 1024px)"
srcSet={`
${baseUrl}?format=auto&w=600 1x,
${baseUrl}?format=auto&w=1200 2x
`}
/>
{/* Tablet: 500px display, serve 1000px for 2x screens */}
<source
media="(min-width: 640px)"
srcSet={`
${baseUrl}?format=auto&w=500 1x,
${baseUrl}?format=auto&w=1000 2x
`}
/>
{/* Mobile: 400px display, serve 800px for 2x screens */}
<source
media="(max-width: 639px)"
srcSet={`
${baseUrl}?format=auto&w=400 1x,
${baseUrl}?format=auto&w=800 2x
`}
/>
{/* Fallback for older browsers */}
<img
src={`${baseUrl}?format=auto&w=400`}
alt={image.label}
loading="lazy"
className={className}
/>
</picture>
)
}
How this works:
1x and 2x descriptors tell the browser which image to use based on device pixel ratio| Prop | Type | Description |
|---|---|---|
image | ImageField | Required. The image object from Agility CMS |
fallbackWidth | number | Optional. Width for the fallback <img> tag. Keep small for mobile performance |
alt | string | Optional. Override the alt text from Agility |
sources | SourceProps[] | Optional. Array of source configurations for responsive images |
priority | boolean | Optional. If true, loads image eagerly instead of lazy |
className | string | Optional. CSS classes applied to the <img> element |
Each source object can include:
| Prop | Type | Description |
|---|---|---|
media | string | CSS media query (e.g., "(min-width: 768px)") |
width | number | Desired image width |
height | number | Optional. Desired image height. Supplying it makes the CDN crop, which is what enables focal points. Without it the crop falls to CSS and is always centred. |
The component generates URLs using Agility's image transformation API:
https://cdn.agilitycms.com/your-image.jpg?format=auto&w=800
format=auto automatically serves WebP or AVIF based on browser supportw=800 resizes the image to 800px wideh=600 would crop to 800x600The component also respects the original image dimensions, so it won't upscale an image beyond its original size. This clamp only applies to width-only or height-only sources; when a source supplies both width and height the clamp is skipped and a larger crop will upscale.
Agility CMS lets content editors set a focal point on an image: the part of the picture that must stay visible when the image gets cropped. The focal point is only applied when the transformation URL carries both a width and a height.
AgilityPic supports this directly. Add height alongside width in a sources entry and the generated URL includes &h=:
| Source entry | Generated URL | Focal point |
|---|---|---|
{ width: 512 } | ?format=auto&w=512 | ❌ Ignored |
{ width: 512, height: 512 } | ?format=auto&w=512&h=512 | ✅ Respected |
This is the part that catches people out, because nothing looks broken. The image just crops in the wrong place.
With width alone, the CDN scales the image proportionally and hands the browser (say) a 512x341 image. If your CSS then forces that into a square box with object-cover, the browser performs the crop, and object-cover always crops from the centre. The focal point is never consulted, because the CDN was never told to crop.
Supplying height moves the crop from the browser to the CDN, which is the only place the focal point is known.
Rule of thumb: any image rendered with
object-coverinto a fixed aspect ratio should specifyheighton every source.
PostCard renders the same post image at three different aspect ratios:
<div className="relative aspect-video sm:aspect-2/1 lg:aspect-square lg:w-64 lg:shrink-0">
Each source therefore needs its own width/height pair matching the ratio rendered at that breakpoint:
<AgilityPic
image={post.image}
fallbackWidth={400}
className="absolute inset-0 w-full h-full object-cover"
sources={[
// aspect-video (16:9)
{ media: "(max-width: 639px)", width: 640, height: 360 },
// sm:aspect-2/1
{ media: "(max-width: 767px)", width: 800, height: 400 },
{ media: "(max-width: 1023px)", width: 1200, height: 600 },
// lg:aspect-square at lg:w-64 (256px), so 2x for retina.
{ media: "(min-width: 1024px)", width: 512, height: 512 },
]}
/>
Because the CDN now returns an image already at the target ratio, object-cover becomes a no-op and the focal-point crop is what the visitor actually sees.
When mixing max-width and min-width queries, make sure every viewport matches a source. It is easy to write a list of max-width rules that stops short and leaves the largest screens with no matching source. Those fall through to the fallbackWidth <img>, which has no height and therefore no focal point. The (min-width: 1024px) entry above exists precisely to catch that case.
AgilityPic caps a request at the source image's own dimensions only for width-only or height-only sources. When both width and height are supplied that clamp is skipped, so requesting a crop larger than the original will upscale it. Upload source images at 2x your largest crop.
The fallback <img> cannot be focal-cropped at all: the component exposes fallbackWidth but no fallbackHeight. As long as your sources cover every breakpoint this is unreachable in practice.
When this matters most:
fallbackWidth (400-800px) for mobile users on 3G networksmin-width queriesmax-width queriespriority={true} for above-the-fold hero imagesheight on every source when the image renders with object-cover, so the focal point is respected