Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A Next.js Image loader builds the URL that the browser uses to request an image; it does not resize or optimize the image itself. Use the loader prop to customize one <Image>, or configure images.loader: 'custom' and images.loaderFile in next.config.js to use a loader across your app. In either case, make the returned URL match the image service that will actually serve or transform the image.
What a Next.js Image loader does
The Next.js Image component extends the HTML <img> element with image-optimization behavior. By default, Next.js can use its own Image Optimization API. A custom loader changes how an image URL is generated so requests can go to an external image service instead. The external service—not the loader function—must serve the image and perform any requested transformations. See the Next.js Image Component reference.
A loader receives a source path, a requested width, and a quality value, then returns a URL string. Next.js can use that function when it needs image URLs for different rendered sizes. The query parameter names and URL structure are not universal: they must be supported by your selected provider, and some providers require account identifiers or transformation syntax of their own.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose a per-image or project-wide loader
| Approach | Scope | Best fit | Trade-off |
|---|---|---|---|
loader prop |
One Image instance | A specific image or a provider-specific exception | Loader logic can be repeated if many images use the same service. |
images.loader and images.loaderFile |
Image instances throughout the project | A centralized URL-generation rule | One default URL scheme may need additional logic for images with different providers. |
Both approaches generate URLs; neither guarantees that a provider accepts them. Check the provider’s documentation for supported widths, quality values, source URL requirements, and any required transformations before using a pattern in production.
#1 Best Overall
Use a custom loader on one Image
Define a function that accepts the documented src, width, and quality arguments, builds a URL your image service understands, and pass it to loader. This example illustrates a service that accepts url, w, and q query parameters. It is not a universal provider format: replace the URL and parameter scheme with the syntax supported by your service.
'use client';
import Image from 'next/image';
function imageServiceLoader({ src, width, quality }) {
const params = new URLSearchParams({
url: src,
w: String(width),
q: String(quality ?? 75),
});
return `https://images.example.com/transform?${params.toString()}`;
}
export default function ArticleImage() {
return (
<Image
loader={imageServiceLoader}
src="https://assets.example.com/article/cover.jpg"
alt="A sample article cover"
width={1200}
height={800}
sizes="(max-width: 768px) 100vw, 800px"
/>
);
}images.example.com and assets.example.com are illustrative placeholders, not working provider endpoints. The loader should return an absolute URL accepted by the chosen service, and the service must be able to access the source image. The component’s width and height provide intrinsic dimensions; sizes describes the rendered layout so responsive image selection can use appropriate widths.
If the loader is declared in a file where Next.js expects a Client Component, retain the 'use client' directive as appropriate for that component and your app’s composition. Keep loader logic deterministic: a given source, width, and quality should reliably yield the intended transformed image URL.
Rank #2
Configure one custom loader for the project
For a shared loader, point images.loaderFile to a project-root-relative file and set images.loader to 'custom'. The file must default-export a function that returns a URL string. The following example uses the same deliberately illustrative query format as above.
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
images: {
loader: 'custom',
loaderFile: './src/lib/image-loader.js',
},
};
module.exports = nextConfig;// src/lib/image-loader.js
export default function imageLoader({ src, width, quality }) {
const params = new URLSearchParams({
url: src,
w: String(width),
q: String(quality ?? 75),
});
return `https://images.example.com/transform?${params.toString()}`;
}Restart the development server after changing Next.js configuration, then inspect the rendered image’s src and srcset in the browser. Confirm that generated URLs point to the intended service and that the service returns the expected image at the requested dimensions. Next.js documents provider configuration and the global loader in its images configuration reference.
The per-instance loader prop remains available when a global loader is configured. Use it when one image needs different URL generation, while recognizing that the resulting URLs still need to be valid for the provider that will handle them.
Restrict remote sources with remotePatterns
When using the default Next.js optimizer with remote images, allow only the sources your app needs. Configure images.remotePatterns with the intended protocol, hostname, path, and—when appropriate—query string. Specific patterns reduce the chance that unrelated remote URLs are accepted. The current docs warn that omitted fields can imply broad wildcards.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'assets.example.com',
pathname: '/account123/**',
},
],
},
};
module.exports = nextConfig;Replace the example host and path with the source locations your app actually uses. The older images.domains setting has been deprecated since Next.js 14; unlike remotePatterns, it does not constrain protocol, port, or pathname. For an external custom loader, also verify the target service’s own source and URL rules; a Next.js allowlist does not make an unsupported provider URL work.
Set image quality for your installed Next.js version
Quality handling depends on the Next.js version and on the image service. The current Image reference says images.qualities is required starting with Next.js 16. Check the version installed in your project and follow the corresponding configuration before adding a setting. For example:
// next.config.js — for a version/configuration that requires qualities
const nextConfig = {
images: {
qualities: [50, 75, 90],
},
};
module.exports = nextConfig;For versions where this option applies, a component request for a quality not in the list is mapped to the closest allowed value; a direct Image Optimization API request with an unlisted quality returns HTTP 400. This is separate from whether an external service recognizes the quality value in the URL generated by your custom loader. Check both the Next.js configuration and the provider’s accepted parameters.
Pick an image service by verifying its contract
The official Next.js configuration page includes loader examples for Akamai, AWS CloudFront, Cloudinary, Cloudflare, Contentful, Fastly, Gumlet, ImageEngine, Imgix, PixelBin, Sanity, Sirv, Supabase, Thumbor, ImageKit, and Nitrogen AIO. These are documented integration examples, not a ranking or endorsement. For any service, verify the details that determine whether its URLs will work for your app:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →- Transformations: confirm it supports the resizing, quality, format, crop, or other operations you intend to request.
- URL syntax: match its documented parameter names, path structure, encoding, and account identifiers exactly.
- Source access: establish whether it can fetch your source images, including any authentication or private-origin constraints.
- Deployment and caching: check how the integration works in your deployment and what caching behavior and limits apply.
- Cost and operational limits: confirm current provider pricing and request or transformation limits directly with that provider; they are not established by the Next.js integration list.
Do not assume that a generic ?w= or ?width= parameter will resize an image. The service must implement that contract. Test URLs for several widths and quality values, including the smallest and largest sizes your layout can request.
Authentication, performance, and reliability considerations
The default Next.js optimizer does not forward request headers when it fetches a source image. If a source requires authentication, the official Image reference advises considering unoptimized. An external loader also does not automatically solve private-source access: use an image delivery arrangement supported by your provider and avoid putting secrets into publicly visible image URLs.
A loader function is small, but the generated URL affects the actual image-delivery path. Performance depends on the provider, source access, transformations, caching, and the sizes requested by the page; no universal speed improvement follows merely from adding a custom loader. Avoid generating unnecessary unique URLs for equivalent image variants, since differences in URL parameters can affect caching. Validate behavior in the deployed environment as well as locally.
Troubleshoot common loader problems
- The image URL contains the wrong parameters. Inspect the rendered
srcandsrcset, then align the loader’s URL structure with the provider’s documented API. - The provider returns an error or the image is unchanged. Open a generated URL directly and check whether the service accepts the source, width, quality, encoding, and requested transformation. A loader only constructs the URL.
- A remote image is rejected by Next.js. If the default optimizer is involved, check that the source matches a sufficiently specific
remotePatternsentry, including protocol and path. - A quality request fails. Check the installed Next.js version and its
images.qualitiesconfiguration; also confirm that the external service accepts the value emitted by your loader. - A protected source fails to load. The default optimizer does not forward request headers. Use an approach supported for authenticated sources, or consider the documented
unoptimizedoption where appropriate. - A global loader is not being used. Verify that
loaderis set to'custom', thatloaderFileis project-root-relative and points to the right file, and that the file default-exports the function. Restart the dev server after configuration edits. - Only one image needs different URL logic. Use that image’s
loaderprop rather than forcing a provider exception into the global rule.
Or skip the browser setup
If your task is to capture a webpage rather than configure next/image, ScreenshotNeo is a separate website screenshot API and MCP server for developers. Its one-call API returns a screenshot or PDF; it is not an image loader or image CDN. See ScreenshotNeo and the API documentation.
Recommended Free Tools
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Next.js Image loader checklist
- Choose a per-image loader for a specific exception or a global loader for the project-wide default.
- Implement a function that accepts
src,width, andqualityand returns a provider-valid URL. - Check remote-source restrictions and version-specific quality configuration for the Next.js version you run.
- Inspect generated URLs and test the resulting images at representative widths in your deployed setup.
Frequently Asked Questions
Can a custom loader process or resize an image by itself?
No. It returns a URL; the image service at that URL must serve the source and perform any requested transformation.
Can I use a global loader and still customize one image?
Yes. The per-image loader prop remains an alternative to the project-wide loader.
Is ScreenshotNeo an image CDN for Next.js loaders?
No. ScreenshotNeo captures website pages as screenshots or PDFs; it is separate from an image transformation service.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
