If your WordPress site looks zoomed out, half-broken, or scrolls sideways on a phone, the cause is almost always one of five things — and you can identify which one in about two minutes without editing a single file. This guide shows you how to find the exact element or setting that is breaking the layout, then fixes each of the five causes in order of how often they turn out to be the answer.
The short answer: the phone is not “rendering WordPress wrong” — it is doing exactly what the page tells it to. Either the page never told the browser to use the phone’s real width (missing viewport tag), or one element inside the layout has a width the phone cannot honour (a fixed-pixel container, a pasted table, an embed). Find that element and the rest is a two-line CSS fix.
| What you see on the phone | What it usually is | Go to |
|---|---|---|
| Everything is tiny; you can pinch out to see the whole page at once | Missing viewport meta tag | Cause 1 |
| One block sticks out and the page scrolls sideways | Something with a fixed width: container, table, image, embed | Causes 2 and 3 |
| Text is squeezed into a narrow column, one or two words per line | Fixed table layout, or a container that never expands | Cause 3 |
| Looks correct in DevTools but wrong on the actual phone | The phone is being served an older stylesheet from cache | Cause 4 |
| Broke after an update and only on some pages | Plugin or theme conflict | Cause 5 |
| Fine in Chrome on Android, broken in Safari on iPhone | iOS viewport behaviour plus cached assets | Diagnose, then Cause 4 |
Diagnose it before you change anything
Three checks, two minutes, no guessing. Do them in this order — each one eliminates a whole category of cause, and the third one tells you exactly which element to fix.
1. Does the page have a viewport tag?
View the page source (Ctrl+U, or Cmd+Option+U on a Mac) and search for viewport. From a terminal:
curl -s https://example.com | grep -i viewport
You want to see exactly this, and only once:
<meta name="viewport"
content="width=device-width, initial-scale=1">
If it is missing, the mobile browser falls back to a desktop virtual canvas about 980 pixels wide and shrinks the whole page to fit the screen. That is the “everything is tiny” symptom, and no amount of CSS will fix it — the browser has already decided how wide the page is.
If you are wondering whether WordPress adds this tag for you: only partly. WordPress core prints the viewport tag for block themes, from a function called _block_template_viewport_meta_tag() that has shipped since version 5.8 and is hooked to run first on the page head. Classic PHP themes get no such tag from core — their header.php has to print it. This is why “WordPress adds it automatically” is true on one site and false on the next.
2. Which element is actually wider than the screen?
Open the site on a phone-sized viewport, open the browser console, and paste this. It lists the elements whose box extends past the left or right edge of the viewport, widest offenders first in document order:
const vw = document.documentElement.clientWidth;
const els = [...document.querySelectorAll('*')];
const box = el => el.getBoundingClientRect();
els.map(el => ({el, r: box(el)}))
.filter(x => x.r.right > vw + 1
|| x.r.left < -1)
.slice(0, 15)
.forEach(x => console.log(
x.el.tagName,
String(x.el.className).slice(0, 40),
Math.round(x.r.right)
));
Nine times out of ten the culprit appears in the first three lines, and it is not the thing you suspected: an image inside a paragraph, a table, an embed, or a slider wrapper with an inline pixel width.
3. Test at 320px and 390px, not “mobile”
Device emulation in developer tools reproduces one thing well: width. It does not reproduce a stale cached stylesheet, iOS handling of viewport units, or touch behaviour. So test in two places — the DevTools responsive mode at 320 × 640 (the narrowest screen you should support) and a real phone on a real mobile connection. If the two disagree, you are looking at cause 4 or cause 5, not a CSS bug.
Cause 1: the missing viewport meta tag
Symptom: the whole page is scaled down. Text is unreadably small, buttons are hard to hit, and zooming in works but the layout still behaves like a desktop page.
Fix for a classic theme: open your child theme’s header.php and add the tag inside <head>, before any stylesheet:
<meta name="viewport"
content="width=device-width, initial-scale=1">
Fix without touching a template file: add the same tag from functions.php of the child theme. Priority 0 puts it first in the head:
add_action('wp_head', function () {
echo '<meta name="viewport" content="'
. 'width=device-width, initial-scale=1">';
}, 0);
Two mistakes to avoid here. First, do not add the tag twice — if the theme already prints one, a second tag can override the first depending on order. Check the rendered source after the change. Second, do not write maximum-scale=1 or user-scalable=no in the tag. Blocking zoom fails the WCAG resize-text requirement (1.4.4) and it does not fix a layout problem; it only stops the visitor from working around one.
Cause 2: a container with a fixed width
Symptom: the page scrolls sideways, or a section’s background stops short and leaves a gap on the right. The content column is wider than the screen and the browser is faithfully scrolling to show you the rest.
Fixed widths arrive from a handful of places, and they are worth checking in this order because the first two account for most cases:
- A page builder’s container setting. A section saved with a pixel content width, or a column given a fixed width instead of a percentage.
- Custom CSS with
min-width.min-widthcannot be overridden by a narrower screen — that is the whole point of it. A singlemin-width: 1100pxon a wrapper breaks every phone. - Inline styles on a block.
style="width:1140px"pasted in with content, often carried over from another site. - Sliders and carousels. Many set an explicit pixel width per slide when they initialise, so a slider that looks fine on desktop overflows on a phone even though the theme is responsive.
!importantrules in a plugin’s stylesheet that win against your theme’s media queries.
Fix: replace fixed widths with a maximum width. width: 1140px becomes max-width: 1140px; width: 100%. Delete min-width on layout wrappers unless it is genuinely required. Then re-run the snippet from step 2 — the offender should disappear from the list.
One clarification, because it trips people up: WordPress does a lot of image work for you automatically. Since the content filter wp_filter_content_tags() runs on the post content, images inserted through the editor get srcset and sizes attributes plus loading="lazy", so the browser can download a smaller file for a small screen. What WordPress does not do is style those images. img { max-width: 100%; height: auto; } is still the theme’s job, and if it is missing, a 2,000-pixel photograph with a width attribute will push the whole layout wider than the phone.
Cause 3: content that physically cannot shrink
Symptom: one specific block breaks the page — usually a table, an embedded video, a code sample, or a long URL. Everything around it is fine.
Tables
This is the most common single cause on content sites, and there is a real difference between two kinds of table:
- A WordPress table block is wrapped and scrolls horizontally on its own. The block library stylesheet sets
.wp-block-table { overflow-x: auto; }, so a wide table scrolls inside its own box instead of pushing the page. - A raw table — pasted from Google Docs or Word, inserted through a plugin, or written by hand in a Custom HTML block — has no wrapper and no scroll behaviour. It simply overflows the page.
There is also a subtler trap in the table block itself: the “Fixed width table cells” toggle adds a class called has-fixed-layout, which sets table-layout: fixed; width: 100% and overflow-wrap: anywhere on the cells. The table will no longer overflow — it will squash instead, and a five-column table at 390 pixels becomes a column of one-word lines. Scrolling is the better behaviour.
Fix for any table: wrap it so it scrolls, and give the table a minimum width so the columns keep their proportions:
<div class="tbl-wrap">
<table>...</table>
</div>
.tbl-wrap { overflow-x: auto; }
.tbl-wrap table { min-width: 640px; }
The wrapper scrolls inside the content column; the page itself never moves sideways. This is also the right fix on a block table that is misbehaving, because it is portable — it travels with the content, not the theme.
Embeds and iframes
A YouTube or map embed arrives with fixed width and height attributes on the iframe. On desktop it looks perfect; on a phone it forces a horizontal scrollbar. Fix:
iframe, video { max-width: 100%; }
.embed { position: relative;
aspect-ratio: 16 / 9; }
.embed iframe { position: absolute;
inset: 0; width: 100%; height: 100%; }
Code blocks and long strings
A <pre> block will not wrap unless you tell it to, and neither will an unbroken URL or an API key. Give the container its own scroll and let prose break long words:
pre, code { overflow-x: auto; }
p, li, a { overflow-wrap: break-word; }
Cause 4: the phone is being served a different, older stylesheet
Symptom: you fixed the CSS, it is correct on desktop, and the phone still shows the old broken layout — sometimes even after a hard refresh. Or the phone is fine on Wi-Fi and broken on mobile data.
Three layers can each hold a stale copy:
- A caching plugin’s page cache. Some also keep a separate mobile cache, keyed on the user agent, so a page cached before your fix keeps being served to phones specifically.
- CSS/JS combine and minify. A combined file keeps the old hash until the cache is purged, so the theme’s corrected stylesheet is never actually loaded.
- A CDN or host-level cache in front of WordPress, which caches the HTML or the CSS at the edge and has its own purge.
How to prove it: load the page on the phone and view the source. If the HTML still contains the old markup or the old CSS filename, the phone is not reaching WordPress at all — the cache is answering. Add a cache-busting query string (?cb=1) and reload: if the layout fixes itself, you have your answer.
Fix: purge the page cache, the minified assets, and the CDN together — in that order. If the problem returns after every edit, turn off mobile-specific caching until the layout work is done, then switch it back on.
A related trap that is worth naming because it looks like a fix and is not: branching your layout on wp_is_mobile(). That function is a user-agent sniff — it checks the browser’s declared identity, or the Sec-CH-UA-Mobile client hint, and returns true or false. It cannot tell you whether the layout is broken, and serving a stripped-down “mobile version” from it costs you content. Google uses the mobile version of a page, crawled with a smartphone agent, for indexing and ranking, so a mobile page with less content than the desktop page is a ranking problem, not an optimisation. Responsive CSS solves the same problem with one document.
Cause 5: a plugin or theme conflict
Symptom: the breakage is recent, appears on some pages and not others, or started right after an update. The console shows JavaScript errors, or stylesheets returning 404.
Do not start deactivating plugins on a live site. Use the Health Check & Troubleshooting plugin (200,000+ active installs): it lets you disable all plugins and switch to a default theme for your own session only, so visitors see the normal site while you test. One caveat worth knowing — it was last updated in July 2024 and is tested to WordPress 6.6, so on a newer install treat it as a diagnostic aid rather than a permanent plugin, and use a staging copy if you have one.
The elimination order that finds the cause fastest:
- Disable all plugins for your session. Reload the broken page at 390px.
- If the layout is correct, re-enable plugins in batches of five, then individually — sliders, page builders, table plugins and “mobile optimiser” plugins first, because they are the usual suspects.
- If the layout is still broken with all plugins off, switch to a default theme for your session. That separates theme from plugin in one step.
- If it only breaks on one page with a default theme and no plugins, the problem is in that page’s content — a pasted table, an inline width, a copied embed — not in the site.
If the breakage followed an update, check the plugin’s changelog for a CSS or responsive change and test the previous version on staging. And look at the browser console before you look at the settings screen: a stylesheet 404 is a much more common cause of “the design fell apart” than any option checkbox.
The baseline that prevents most of this
Six rules cover nearly every case above. Put them in the child theme’s stylesheet, or in Appearance → Customise → Additional CSS if you do not have a child theme. A theme that ships without them is the reason so many sites break the same way — it is worth checking which themes are actually built for this before you patch a bad one.
img, video, iframe { max-width: 100%; }
img { height: auto; }
.wrap { width: 100%; max-width: 1140px; }
.tbl-wrap { overflow-x: auto; }
.tbl-wrap table { min-width: 640px; }
pre, code { overflow-x: auto; }
p, li, a { overflow-wrap: break-word; }
What is deliberately not in that list is body { overflow-x: hidden; }. It is the most commonly recommended one-line fix for this problem and it is a bad one: it hides the overflow instead of removing it, it can break sticky headers and scroll-linked effects, and it leaves the element that is too wide still too wide — just invisible. Use it only as a temporary test, never as the fix.
How to verify the fix actually landed
Do not judge by eye at one width. Run this at 320, 390 and 768 pixels — it returns true when nothing is overflowing:
document.documentElement.scrollWidth
<= document.documentElement.clientWidth
Then check the numbers Google actually uses, in PageSpeed Insights, on the mobile tab: Core Web Vitals are rated on the 75th percentile of real visits, with “good” meaning Largest Contentful Paint at or under 2.5 seconds, Interaction to Next Paint at or under 200 milliseconds, and Cumulative Layout Shift at or under 0.1. A layout that looks right but shifts as images load will still fail CLS, and that is a content problem with a CSS fix — set width and height on images so the browser reserves the space.
Finally, tap through the page with a thumb rather than a mouse: check the menu, the search box, and any form. Touch targets that are smaller or closer together than a fingertip are a separate defect from layout overflow, and they are the second thing visitors complain about after sideways scrolling.
When it is not CSS at all
A few situations look like this bug and are not:
- Only one page is broken, the rest is fine. The theme is not the cause. The page’s own content contains the offending element — a table, an embed, a copied inline style. Fix it in the page, not in the theme.
- Every page is broken, and the site was migrated recently. Check that the new server is not serving a cached copy of the old site, and that the theme’s stylesheet is actually loading (a 404 in the console, not a layout bug).
- The site is fine but the menu does not open. That is JavaScript, not responsive CSS — the script that toggles the mobile menu is failing, usually because of a minification or defer setting.
- Block theme versus classic theme. If you are on a block theme, the viewport tag comes from core and is not something you can forget. If you are on a classic theme, it is the first thing to check.
If you would rather not work through this on a live site, our WordPress care plans cover exactly this kind of diagnosis: updates applied on a staging copy first, the site checked at mobile widths after every change, and someone else on the hook when something breaks at 2am.
Frequently asked questions
Does WordPress add the viewport meta tag automatically?
For block themes, yes — core prints it. For classic themes, no: the tag has to come from the theme’s header.php or from a small function hooked to wp_head. That is why two WordPress sites can behave completely differently when the same phone loads them.
Why is my site tiny and zoomed out on mobile?
Almost always a missing viewport tag. Without it the browser assumes a desktop-width canvas and scales the page down to fit the screen. Confirm it by searching the page source for viewport, then add the tag as shown in cause 1.
Why does the site look fine in developer tools but broken on a real phone?
Device emulation changes the viewport width and little else. It does not serve the cached stylesheet the phone may be getting, it does not reproduce iOS’s handling of viewport units, and it does not test touch. When the two disagree, suspect caching first and the browser second.
Will changing the theme fix it?
Only if the theme is the cause. Test before you commit: open the Customiser, preview a default theme such as Twenty Twenty-Five, and load the same page at 390 pixels. If the layout is still broken in the preview, the problem is a plugin or the page content and a new theme will not solve it. If you do end up shopping for one, start with what it does at 390 pixels, not with the demo screenshot.
Does a broken mobile layout affect SEO?
Yes, though not in the way most articles describe it. What matters is that Google uses the mobile version of the page for indexing and ranking, so mobile and desktop should carry the same content and the same metadata. A mobile layout that hides sections, strips text, or keeps content out of the markup is the version being judged.
Can I just hide the overflow with CSS?
You can, and it will look fixed, and the element causing it will still be too wide. overflow-x: hidden on the body also interferes with sticky positioning and scroll behaviour. Find the element with the snippet in step 2 and fix its width instead.
Is a “mobile optimiser” plugin the answer to this?
Usually not. A responsive theme plus the six CSS rules above handle the layout. Plugins that promise a separate mobile version tend to produce a second, thinner page — and with mobile-first indexing, that thinner page is the one Google evaluates.