My Responsive Website Isn’t Working. The Fix: Viewport.

A friend of mine recently contacted me to ask for help with a WordPress site he had built using the X theme. His client had called him that morning after he noticed that his website wasn’t displaying correctly on his iPhone. Nick checked it out himself, and sure enough, the beautiful responsive design he designed wasn’t working anymore.

He was further mystified by the fact that when he resized his browser window on his desktop, the site was responsive, but on his iPhone, only the desktop version was displayed. Why would a site be responsive on a desktop computer and non-responsive on a mobile device?

Why Responsive Design Doesn’t Work

Responsive design stops working when one line of code is missing from the header of an HTML file. If this single line of code is missing, your iPhone, Android, and other mobile devices will assume that the website you’re viewing is a full-size desktop site and adjust the size of the viewport to encompass the entire screen.

What Do You Mean By Viewport and Viewport Size?

On all devices, the size of the viewport refers to the size of the area of a webpage that is currently visible to the user. Imagine you’re holding an iPhone 5 with a width of 320 pixels. Unless explicitly told otherwise, iPhones assume that every website you visit is a desktop site with a width of 980px.

Now, using your imaginary iPhone 5, you visit a website designed for desktop that is 800px wide. It doesn’t have a responsive layout, so your iPhone displays the full-width desktop version. 

But an iPhone 5 is only 320 pixels wide. Isn’t that always the size of the viewport?

No, it’s not. With viewport size, scaling can be involved. The iPhone has to zoom out to see the full-width version of the webpage. Remember that viewport refers to the area of a page that is currently visible to the user. Is the iPhone user currently seeing just 320 pixels of the page, or are they seeing the full-width version?

That’s right: They’re seeing the full-width webpage on their display because the iPhone has assumed it’s default behavior: It’s zoomed out so the user could view a webpage up to a width of 980 pixels. Therefore, the iPhone’s viewport is 980px.

As you zoom in or out, the viewport size changes. We said before that our imaginary website has a width of 800px, so if you were to zoom in your iPhone so that the edges of the website were touching the edges of your iPhone’s display, the viewport would be 800px. The iPhone can have a viewport of 320px on a desktop site, but if it did, you’d only be seeing a small portion of it.

My Responsive Website Is Broken. How Do I Fix It?

The answer is a single line of HTML that when inserted in the header of a webpage tells the device to set the viewport to it’s own width (320px in the case of an iPhone 5) and not to scale (or zoom) the page.

For a more technical discussion of all the options related to this meta tag, check out this article on

How To Fix WordPress X Theme When It Isn’t Responsive

Back to my friend from before: This one line of code disappeared when he updated the X theme. When fixing yours, keep in mind that the X theme doesn’t use just one header file – it uses different header files for every stack, so you’ll have to edit yours.

Since Nick uses the Ethos stack of X theme, he had to add line of code I mentioned before to the header file that was located in x/frameworks/views/ethos/wp-header.php. If you use a different stack, substitute the name of your stack (Integrity, Renew, etc.) for ‘ethos’ to find the correct header file. Insert that one line, and voila! You’re good to go.

So This Fixes My CSS Media Queries, Too?

When you insert that line in the header of your HTML file, your responsive @media queries will suddenly begin to work again and the mobile version of your website will spring back to life. Thanks for reading and I hope it helps!

Remember to Payette Forward,
David P.


About Author

I'm a former Apple employee and the founder of Payette Forward, and I'm here to help you with your iPhone.