Table of contents9
Two years ago I opened my blog on a friend’s phone and watched a 2400-pixel-wide hero image crawl down the screen over café Wi-Fi. My desktop showed the same page in a blink. Same site, same image — but her phone had downloaded a file six times bigger than its screen could ever display. The culprit was missing WordPress responsive images srcset markup: my site was serving desktop-sized files to a phone.
That evening I learned the fix was already built into my site: WordPress responsive images srcset markup, generated automatically since version 4.4. My site just wasn’t using it properly. I’ve since audited dozens of WordPress sites, and broken or missing responsive image markup is one of the most common silent speed killers I find.
Here’s the fear I hear most: “srcset sounds like developer stuff.” It isn’t. You don’t need to write a line of code to benefit from it — but you do need to understand what it’s doing, because when it breaks, it breaks quietly, and your mobile visitors pay the price in megabytes.
In this guide I’ll explain WordPress responsive images and srcset in plain language: how WordPress automatically builds multiple image sizes behind your back, what the srcset and sizes attributes actually do, how to verify they’re working on your site in under a minute, and how to fix the three problems I see most often.
This is for WordPress site owners who want their images to load fast on every device without touching code. Let’s start with the problem that made all of this necessary.
One promise before we dive in: by the end of this article you’ll be able to open your browser’s developer tools, look at any image on your site, and tell in ten seconds whether WordPress responsive images are working or silently failing. That’s a skill that pays off on every page you ever publish.
What You’ll Learn in This Guide
- See the exact problem responsive images solve, with real numbers
- Understand how WordPress builds srcset markup automatically on every upload
- Learn what the sizes attribute does — and why getting it wrong wastes bandwidth
- Verify in under a minute that srcset is working on your own site
- Fix the three most common srcset problems without touching code
- Take control with custom image sizes when your theme needs them
Ready? Let’s get started.
The Problem srcset Was Built to Solve
Before responsive images existed, every visitor got the same file. Your phone with its 390-pixel-wide screen downloaded the same 2400-pixel hero image as a 27-inch desktop monitor. The phone then shrunk it down with CSS — but the megabytes were already spent. On mobile data, that’s not a minor inefficiency. It’s the difference between a page that feels instant and one that feels broken.
I measured this on my own site back in the day. My homepage hero was a 1.8 MB file. On a phone, the browser displayed it at 390 pixels wide — using roughly one fortieth of the pixels I’d forced the visitor to download. Multiply that waste across every image on a page, and you start to see why mobile bounce rates were so brutal.
The old workaround was server-side device detection: sniff the visitor’s device, then serve a different page. It was fragile, complicated, and doubled everyone’s maintenance work. Responsive images took the opposite approach — send the browser a menu of available sizes up front, and let the browser itself pick the right one. All the decision-making moved to where it belongs: the device that knows its own screen.
How WordPress Responsive Images srcset Really Works
Here’s the part that surprised me when I first dug into it: WordPress does almost all of this automatically, and it has since version 4.4. The moment you upload an image to the Media Library, WordPress generates several smaller copies — thumbnail, medium, large, and any custom sizes your theme registered. Upload one 2400-pixel photo, and WordPress quietly creates a whole family of smaller versions alongside it.
Then, when you insert that image into a post or page, WordPress writes HTML that looks something like this:
<img src="photo.jpg"
srcset="photo-300.jpg 300w, photo-768.jpg 768w, photo-1024.jpg 1024w, photo.jpg 2400w"
sizes="(max-width: 1024px) 100vw, 1024px"
alt="A photo">The srcset attribute is the menu: a list of image files, each labeled with its width in pixels (that’s what the “w” means — 300w is a 300-pixel-wide file). The browser reads this list, checks the visitor’s screen size and pixel density, and downloads the smallest file that will still look sharp. A phone gets the 300-pixel version. A laptop gets the 1024. Nobody downloads more than they need.
The src attribute is still there as a fallback for ancient browsers that don’t understand srcset — and as the default the browser shows while it decides. And there’s one more attribute in that markup doing quiet, critical work — the sizes attribute, which this whole WordPress responsive images srcset system depends on. It deserves its own section, because it’s where most sites go wrong.
One important detail from the official WordPress developer docs: WordPress never adds or modifies srcset and sizes if they already exist in your content HTML. So if you pasted in raw HTML with your own img tags — or a page builder wrote its own markup — WordPress politely steps aside, and you get no responsive behavior at all. I’ll show you how to spot that in the verification section.
What the sizes Attribute Does (and Why It’s the Number One Mistake)
If srcset is the menu, sizes is the browser’s cheat sheet. It answers one question: how wide will this image actually display at different screen widths? Something like sizes="(max-width: 768px) 100vw, 50vw" tells the browser: on screens narrower than 768 pixels, this image spans the full viewport width; on wider screens, it takes half.
Here’s why it matters so much: the browser has to choose an image file before the page’s CSS has finished loading. It can’t measure the image yet — layout isn’t done. So sizes gives it the layout information early, letting it pick correctly on the first try instead of guessing.
And here’s the mistake I see constantly. When sizes is missing or wrong, the browser assumes the image will be 100vw — the full viewport width. For a sidebar image that only displays at 300 pixels, that assumption makes the browser download a file four times bigger than necessary. Every column image, every thumbnail, every gallery grid silently over-downloads because of one missing attribute.
The good news: for images you insert through the WordPress editor, WordPress writes a sensible sizes value for you. The bad news: themes with unusual layouts sometimes need a better one. There’s also a newer option worth knowing — sizes="auto" — which lets the browser use the image’s actual rendered size for lazy-loaded images, since layout is known by the time they load. Recent WordPress versions add this automatically for lazy-loaded images, which pairs beautifully with the techniques in our lazy loading guide.
My rule of thumb: sizes doesn’t need to be perfect. Being approximately right about your layout is enough to avoid the big over-downloads. Being missing is what costs you.
Verify srcset Is Working on Your Site in Under a Minute
Theory is nice, but I never trust it. Here’s the sixty-second check I run on every site I touch — no plugins, no tools, just your browser.
Open any page with images, right-click an image, and choose Inspect. In the developer tools panel, look at the img tag. If you see a srcset attribute with multiple file URLs and width descriptors, your WordPress responsive images srcset output is healthy for that image. If you only see a lonely src attribute, they’re not — and now you know exactly where to look.
Want proof the browser is actually choosing wisely? In the same developer tools, open the Network tab, filter by Img, then reload the page. It shows you the exact file the browser downloaded and its size. Now resize your browser window narrow — like a phone — and reload again. If srcset is working, you’ll see the browser grab a smaller file. I do this little before-and-after on every site, and the difference is usually dramatic: a 1.2 MB desktop file becomes a 90 KB mobile file.
Bonus Tip: test with network throttling set to “Fast 3G” in the Network tab. It simulates a real mobile connection and makes the benefit visceral — you’ll feel the page snap in instead of crawl. Numbers on a report are abstract; watching it happen is convincing.
Fixing Common WordPress Responsive Images srcset Problems
When the verification check fails, it’s almost always one of these three. The fixes are simpler than you’d expect.
Problem 1: no srcset at all. The image tag has only a src attribute. This usually means the image wasn’t inserted through the WordPress editor — it came from raw HTML you pasted in, a widget with a hardcoded img tag, or old content written before your theme supported responsive images. The fix: re-insert the image through the editor using the Image block (our block editor guide walks through the Image block settings), or replace the hardcoded tag with the proper WordPress function if it’s in a template.
Problem 2: srcset exists but the sizes are wrong. You’ll see this as a srcset list where every option is tiny, or a sizes attribute that doesn’t match your layout — like 100vw on an image that clearly sits in a narrow column. The most common cause: the image was uploaded before your theme registered its custom sizes, so WordPress never generated the versions srcset needs. The fix is to regenerate the image sizes for your media library — a free thumbnail-regeneration tool from the WordPress plugin directory does this in one batch run. Afterward, clear your cache so the new markup reaches visitors.
Problem 3: the browser picks a file that’s too small and looks blurry. This one confused me for a while. It happens when the original upload was smaller than the display size — if you upload an 800-pixel image and display it at 1200 pixels, no srcset magic can invent the missing pixels. The fix isn’t in srcset at all: upload a larger original. Responsive images can only choose from the sizes that exist.
Taking Control: Custom Image Sizes Done Right
Most of the time, WordPress defaults plus your theme’s sizes are plenty. But when your design has a specific slot — say, a card layout that always displays images at exactly 640 pixels wide — a custom size stops the browser from settling for “close enough.”
Developers register these with a single line in the theme, using WordPress’s built-in add_image_size() function — for example, registering a 640-pixel-wide “card” size. WordPress then generates that size for every new upload and automatically includes it in the srcset menu. If you’re not comfortable editing theme files, this is a five-minute job for any WordPress developer, and it’s the kind of one-time setup that quietly improves every future upload.
One caution from experience: don’t register a dozen custom sizes “just in case.” Every registered size means another file generated per upload — more disk space, slower uploads, and a more cluttered srcset menu. I audit my registered sizes once a year and remove any my design no longer uses. Three to five purposeful sizes beat twelve speculative ones.
Combined with the steps in our complete WordPress speed checklist, properly working responsive images are one of those invisible upgrades — visitors never notice them, which is exactly the point. They just feel your site as fast.
Frequently Asked Questions
Does WordPress create responsive images automatically? Yes — since WordPress 4.4, every upload automatically gets multiple resized copies, and images inserted through the editor get srcset and sizes attributes with no configuration needed. It only skips images where the markup already exists, like pasted raw HTML.
What is the difference between srcset and sizes? srcset is the menu of available image files with their widths; sizes tells the browser how wide the image will display at various screen widths so it can pick the right file before CSS loads. You need both — srcset without sizes makes browsers assume full viewport width and over-download.
Why is my browser downloading the largest image on mobile? Almost always a missing or wrong sizes attribute. Check with Inspect: if sizes says 100vw for an image that displays in a narrow column, the browser has no choice but to grab a big file. Fix the sizes value to match your actual layout.
Do I need srcset if I already compress my images? Yes — they solve different problems. Compression makes each file smaller; srcset makes sure each device downloads the appropriately sized file in the first place. A perfectly compressed 2400-pixel image is still wasteful on a phone. Use both.
Can srcset hurt image quality on high-resolution screens? Not when it’s working correctly. The browser multiplies the display width by the device’s pixel ratio — so a phone with a 3x retina display asking for a 390-pixel-wide slot will pick a file around 1170 pixels wide. Sharp on retina, still far smaller than the full original.
Final Thoughts
Responsive images are one of those rare web features that ask nothing of you and give a lot back. WordPress builds the sizes, writes the markup, and the browser does the choosing. Your only real job is the one this article just gave you: verify it’s actually working, and fix it on the rare occasions it isn’t.
If you ran the sixty-second Inspect check on your own site while reading, you’ve already done the most valuable part. Most site owners never look — and their mobile visitors quietly pay for it on every page.
Honest confession: I ignored srcset for years because the name sounded intimidating. It turned out to be one of the simplest concepts in web performance — a menu, a cheat sheet, and a browser smart enough to order correctly. Don’t let the jargon keep you from a free speed win.
Go inspect one image on your site right now, then tell me in the comments what you found — working srcset, or one of the three problems above? Your answer helps me know which fixes to cover in more depth next time.
