CSS media queries for mobile on WordPress

A common snippet for mobile CSS is @media (max-width: 767px) { ... }. It applies its rules when the viewport is 767 CSS pixels wide or narrower. That includes a phone, and it also includes a laptop browser window dragged narrow. The number is a convention, not a standard.

On WordPress sites, people usually notice this when a mobile fix looks right in the editor and wrong on their phone. Most of the time the media query is fine. Something else wins: a cached stylesheet, a builder setting, or a more specific selector. This guide covers how to write the query, where to put it, and how to find the actual cause when it doesn’t apply.

What a mobile media query actually tests

A media query is a condition. The browser checks it and applies the rules inside only when it is true. For layout, that condition is almost always the viewport width in CSS pixels. Elementor’s responsive editing docs make the same point: a breakpoint applies to any screen at that width, whatever the device.

You can write the condition in two directions:

/* Desktop-first: base styles are for wide screens, this overrides them on narrow ones */
@media (max-width: 767px) {
  .site-columns { flex-direction: column; }
}

/* Mobile-first: base styles are for phones, this adds layout on wider screens */
.site-columns { display: flex; flex-direction: column; }
@media (min-width: 768px) {
  .site-columns { flex-direction: row; }
}

Use width, max-width and min-width. Avoid max-device-width. It measures the physical screen rather than the viewport the page is laid out in, so it can disagree with what visitors actually see. If you want the bigger picture of how themes and builders split layout control, start with how layout works on WordPress.

Which breakpoint should you use for mobile?

No single number is correct. Media queries test conditions, and the familiar values come from tool defaults:

Source	Mobile	Tablet
WordPress responsive styles (block themes, WordPress 7.1+)	480px and below	Up to 782px
Elementor defaults	767px	1024px
Common desktop-first CSS	max-width: 767px	Varies by theme

MDN recommends adding a breakpoint where the layout starts to fail, not at a device size. Drag the browser narrower until something looks cramped, overlaps or overflows, and put the breakpoint just above that width. WordPress’s CSS Coding Standards say to test above and below every breakpoint you add.

There is one practical exception. If the page is built in Elementor, or a block theme uses responsive styles, use that tool’s breakpoint for your custom CSS too. If your CSS switches at 600px and the builder switches at 767px, the layout spends 167 pixels half-converted.

Check the viewport tag before anything else

Without a viewport meta tag, mobile browsers can lay the page out on a wider virtual viewport and then shrink it to fit. The W3C CSS Viewport spec describes this older behaviour. When it happens, your max-width: 767px query never matches, and changing the number won’t fix it.

Open the live page, view the source, and search for viewport. You want something like:

<meta name="viewport" content="width=device-width, initial-scale=1">

Almost every current theme outputs this already, so check before you add one. A duplicate tag won’t help. If the existing tag contains user-scalable=no or maximum-scale=1, it is stopping visitors from zooming. Fixing that belongs in the theme or a child theme, not in Additional CSS.

How to add a mobile media query in WordPress

You need an administrator login and a desktop browser with developer tools. Chrome, Firefox and Edge all work.

1. Find the element and the rule that currently wins. Right-click the element and choose Inspect. Turn on the device toolbar (Ctrl+Shift+M, or Cmd+Shift+M on a Mac) and set a phone width. Note the element’s class and which rule is applied. Crossed-out rules have been overridden.
2. Look for a setting before writing code. In a block theme on WordPress 7.1 or later, responsive styles let you set mobile and tablet values for a block. In Elementor, use the device switcher in the editor or Advanced > Responsive. If a setting does what you need, use it.
3. Open the site-wide Additional CSS. On a classic theme it is under Appearance > Customize > Additional CSS. On a block theme, go to Appearance > Editor > Styles and open Additional CSS from the Styles panel’s menu.
4. Write the rule using the selector you found. Put your override after any rule it needs to beat.
5. Save, clear caches, and test at several widths. The test is described in the next section.

Here is a real case. In a WooCommerce support thread, a store owner’s Add to Cart button looked fine on a laptop and wrong on phones. The fix was to wrap the button styles in a 600px query, which made the button full width with a smaller font. The owner replied “It worked perfectly.” The pattern looks like this:

@media (max-width: 600px) {
  .single_add_to_cart_button.button.alt {
    display: block;
    width: 100%;
    font-size: 14px;
  }
}

Watch out for the second CSS field. Each block type in the Styles panel also has its own Additional CSS box, and WordPress’s Styles documentation says it takes declarations only, with no selectors and no braces. A full @media rule pasted there will not work. Also note that Additional CSS survives theme updates but is cleared when you switch themes. Keep a copy, and move anything substantial into a child theme. The guide to theme customization that survives updates covers which layer to choose.

Patterns that cut down on breakpoints

Many mobile problems are overflow, not layout. These rules fix a lot of them without a breakpoint:

img, video, iframe { max-width: 100%; height: auto; }
.entry-content { overflow-wrap: break-word; } /* long URLs */
h1 { font-size: clamp(1.75rem, 5vw, 3rem); }  /* fluid heading */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
}

Keep media queries for changes that are real layout shifts: switching the menu, stacking columns, reflowing a table, showing or hiding a secondary element. Use fluid sizing for everything else.

What a correct result looks like

The rule should apply at every width below your breakpoint and at none above it. Check it in the device toolbar at 320, 375 and 414 pixels, then just above and just below the breakpoint. At 320 CSS pixels, nothing should scroll sideways and nothing should be cut off. That width comes from WCAG 1.4.10 Reflow, which asks that vertically scrolling content keep all its information and functions at that width without two-dimensional scrolling.

Then open the page on a real phone in a private tab. Builder device previews are not always a real viewport. A Stack Exchange question about Gutenberg’s preview describes it narrowing the container instead, so a rule can pass in preview and fail on the phone.

Why mobile CSS works in preview but not on your phone

These causes come up again and again in WordPress support threads. They are listed roughly from most to least often reported. This order comes from reading the threads, not from a survey.

1. The phone is getting old CSS

Page builders write CSS to files, and caching or optimization plugins combine and minify those files. Your edit saves, but the phone receives the previous version. In Elementor, go to Elementor > Editor > Tools and run Clear Files & Data. Then clear the caching plugin, then the host or CDN cache, then the browser cache. In one resolved LiteSpeed Cache thread, GeneratePress’s dynamic CSS kept being served stale on mobile until the affected files were excluded from CSS optimization. If a purge doesn’t stick, the guide to pages that won’t update walks through each cache layer.

2. A builder or theme setting overrides it

Elementor’s mobile troubleshooting guide lists the usual suspects. They are Advanced > Responsive > Hide On, widget-level Custom CSS, site-wide custom code, and theme or plugin conflicts. Some older themes and plugins also serve a separate mobile theme. Turn it off before you debug CSS that the phone never loads.

3. The selector doesn’t match or loses

Builders wrap each widget in several divs, so a selector copied from a tutorial often matches nothing. Copy the class from the live page in DevTools. If the selector matches but loses, put your rule after the base rule, or make it a little more specific. Add !important only when the rule you are overriding already uses it. If you add !important to everything, the next fix gets harder.

4. The syntax is broken and fails silently

CSS doesn’t show errors. A missing closing brace can swallow every rule after it. In one WordPress.com forum case, the query said screen2 instead of screen. Sydney theme support told another user that an invalid line in Additional CSS can stop the lines after it from working. Paste your CSS into a validator, or check that DevTools lists your rule at all.

5. The CSS is in the wrong field or never loads

Media queries in the per-block field, CSS inside a page’s content, or a stylesheet that isn’t enqueued on that template all look like “mobile CSS not working”. In DevTools, check that your rule is present in the Styles panel at a phone width.

When to stop and get help

Get help if you have ruled out all five and the rule still doesn’t apply. Builder plugins have their own bugs. Elementor Pro 3.24.5, for example, fixed responsive styles not loading in Apple’s WebKit. Some threads never find a root cause. Gather the page URL, the width where it breaks, the element and the winning rule from DevTools, and send them to the theme or plugin’s support. If you would rather describe the problem than track it down, SiteSelf can make theme-level design and mobile styling changes on request from chat, with hosting access. Pages owned by Elementor, Divi or Beaver Builder are refused, and you are told why.

Be careful what you hide on mobile

The easy mobile fix is display: none. It also removes the element for screen readers. Google indexes and ranks the mobile version of a page and advises against removing primary content there. Accordions and tabs are fine. Hiding a decorative image or a duplicate call to action is fine. Hiding prices, product details or the text that explains your offer is not.