Solving the Lighthouse 'content is not sized correctly for the viewport' Failed Test

failure-chalkboardAre you trying to build a Progressive Web App and Using Lighthouse to audit your site's quality?

Chances are you are seeing a failed test about your page's width.

"content is not sized correctly for the viewport"

If you routinely run your web pages through Lighthouse you might see the issue listed in the Progressive Web App category. The Lighthouse documentation has a small page explaining the test and recommendations.

Its content is weak.

It is common to fail a test telling you the page's content is wider than the viewport: "content is not sized correctly for the viewport".

First you try to decipher what Lighthouse is trying to tell you. Then you try to figure out how to fix the issue.

In this article you will learn more about this 'wide-load' scenario, how to fix the issue and why having a good mobile first layout and user experience is important to the success of all web sites and progressive web apps.

What the Lighthouse Viewport Test Does

This means there is at least one element in your page that renders wider than the available viewport, which really means wider than the device screen. This is problematic for mobile devices, which are more important today than the past.

The audit passes if window.innerWidth === window.outerWidth

The Lighthouse documentation says you can ignore this rule if:

  • Your site does not need to be optimized for mobile screens.
  • The content width of your page is intentionally smaller or larger than the viewport width.

But can you really?

There should be no reason your layout does not match the viewport width.

Why Mobile First Responsive Design is Important For All Web Sites (Even Yours)

Most likely you are not creating a site for desktop only. There are a few cases where you might want to focus solely on desktop. The most common scenario I hear goes something like: 'it’s just a tool for our own needs' or 'we are only using it in house on their desktops'.

First, the majority of digital activity is done using mobile devices. This is such a reality that Google has now switched their primary search index to mobile. They are in the process of deprecating their desktop index based on what I have read.

This issue is also tested by the Google search spider. You may find a similar issue reported in the Google Search Console.

"This report indicates pages where horizontal scrolling is necessary to see words and images on the page. This happens when pages use absolute values in CSS declarations, or use images designed to look best at a specific browser width (such as 980px). To fix this error, make sure the pages use relative width and position values for CSS elements, and make sure images can scale as well."

This is particularly important as the Google search team has migrated just about every website over to their mobile index as the primary index.

But Chris, we are not building a public application, so mobile doesn't matter.

If that is your mentality you are hurting not only yourself but your customer or stakeholder. To say we or your company is desktop only is a limiting decision that will be 'hacked' around by your employees and customers. They will use the device(s) they want.

Gone are the days where the IT department can limit the hardware used by employees. The democratization of IT is a reality, even if it is not a formal corporate policy.

"Any attempt to draw a line around a particular device class has as much permanence as a literal line in the sand. Pause for a moment and the line blurs. Look away and it will be gone. Let’s take the absolute best case scenario. You’re building a web app for internal users for whom you get to specify what computer is purchased and used. You can specify the browser, the monitor size, keyboard, etc. How long do you think that hardware will be able to be found? Three years from now when a computer dies and has to be replaced, what are the chances that the new monitor will be a touchscreen? By making a decision to design solely for a “desktop UI”, you are creating technical debt and limiting the longevity of the app you’re building. You’re designing to a collective hallucination. You don’t have to have a crystal ball to see where things are headed. And once you start accepting the reality that the lines inside form factors are as blurry as the lines between them, then responsiveness becomes a necessity." Jason Grigsby

In short, your end users will use mobile devices, if not today, tomorrow. Your software has to provide a productive experience for all screen sizes.

The Viewport should be used to guide your layout decisions. Luke Wroblewski stated in 2013:

Responsive Web designs rely on an understanding of screen size as determined by the viewport of a Web browser. This one measure is often used to make many important decisions.

...A browser’s viewport size is just that -a measure of how much screen real estate (in relative pixels) an interface should use in order to be comfortably viewed on a specific device. That’s why viewport is great for determining how what you put on a screen should lay out.

This is why you need to pass this Lighthouse test.

Having a layout wider than the available viewport just feels unprofessional. You have some content just slough off to the right, breaking a well thought out layout.

Just because one element is too wide, the remaining elements lose their design aesthetics, and can cause navigation issues and leave a bad impression on your visitor.

Fixing Your Wide-Load Issues

Enough with why having a mobile-first design is important. Let's fix your problem.

The first place I look is images. They can often push your page's width wider than the available viewport because they are either as wide or wider than the viewport.

This is where using a good responsive image strategy helps.

First, make sure you always have a set of images specified using the srcset attribute. You will also need to add a sizes attribute. All browsers support these key responsive image properties.

 <img data-srcset="img/progressive-web-app-course-card-1200x632.png 1200w, img/progressive-web-app-course-card-980x517.png 980w,img/progressive-web-app-course-card-720x380.png 720w, img/progressive-web-app-course-card-460x243.png 460w,img/progressive-web-app-course-card-320x169.png 320w" sizes="(max-width: 480px) 95vw, 25vw" data-src="img/progressive-web-app-course-card-1200x632.png" alt="Progressive Web Apps From Beginner to Exper $29!" class="lazy-image" /> 

First, what is srcset?

mobile-too-wide-viewport-layoutThis attribute's value is a command separated list of images followed by a value indicating its width. Each image should, ideally, be the same image of different, progressively smaller or larger dimensions. I always start with the largest size.

The width value indicates how many pixels wide the image is. The value format is ###w. The 'w' is shorthand for width and the number is the number of pixels.

The sizes attribute is a collection of directives to tell the browser how wide to render the image. The sizes syntax uses media queries followed by a width value. I typically use max-width in my media queries, but you can use any valid media query syntax.

OK, so how does this help solve your Lighthouse test issue?

Many times, you use sizes values that cause the image to render larger than the available space. A common reason why this happens is the image is designated a width with a related margin and/or padding that combines to be wider than the viewport.

If this is the problem, then change your sizes rule to reduce the image's width. You may also consider adjusting the margin and padding related to the image. You should note images are typically nested within other elements that can have extra padding, margins and even borders that combine to expand the rendered width.

Wide Child Elements

This leads to the next issue, you have an element or combination of elements that require extra width. So far, my experience has shown not having text that properly wrap could be the issue. Maybe you have a long word that won't break? In these situations, you may need to reduce the font-size.

Another trick I have used when all else fails is to apply overflow: hidden or scroll to a parent element. This causes the outer elements to fit the available viewport even when the child element(s) are wider.

The wide elements will 'scroll' horizontally if scroll is set or just get clipped when hidden is chosen.

Sometimes it takes some trial and error to spot the offending element. And to be honest it may not be apparent at first which element is breaking the layout.

I use the F12 tools to examine all the elements in the offending section. Here you can see an element's dimensions, how the margins and paddings are applied and try to adjust them to see what fixes the issue.

Use Adaptive - Fluid Mobile First Responsive Layouts

Just like that long sub-heading implies you need to have some sort of flexible layout. This means the layout should grow and shrink with the viewport width.

To achieve this, you should not use pixels to define widths. Instead use flexible units like percentage, em, rem and vw.

Each of these units is based either on the size of the container element, current font-size or the viewport itself.

But there is more to it than just adjusting an element's width. You need to make your layout 'adapt' to the screen size.

Adaptive layouts adjust not only to the viewport but adjust the layout to make it more usable for the available screen size.

A common example is the use of the hamburger menu to hide and collapse header navigation on smaller screens.


If you fail the Lighthouse Viewport width test you should take action and don't ignore this failed test. The reason you want to address the problem is to make sure you deliver the nest user experience.

The common issue is an improperly sized child element, like an image, causing your layout to break. This causes the layout to be wider than the screen, which conveys an unprofessional image to customers.

You want to provide the best experience possible, so your business can be as successful as possible.

Share This Article With Your Friends!

We use cookies to give you the best experience possible. By continuing, we'll assume you're cool with our cookie policy.

Install Love2Dev for quick, easy access from your homescreen or start menu.

Googles Ads Facebook Pixel Bing Pixel LinkedIn Pixel