Ad code & integration

Unfilled AdSense ad slots: reading data-ad-status and handling blank spaces cleanly

Last updated Published By the editorial team6 min5 sources

Key takeaways

  • After an ad request completes, AdSense adds data-ad-status to the ins element with the value "filled", "unfilled" or "unfill-optimized".
  • AdSense collapses unfilled units only when they are outside the viewport; unfilled units in view keep their size and show blank space.
  • Google documents the CSS selector ins.adsbygoogle[data-ad-status="unfilled"] with display: none !important to hide unfilled units.
  • data-ad-status is only added to ad units in the top window, not to units served through a cross-domain frame.
  • Google advises against loading ad units hidden and revealing them on a status change, because hidden units may never send an ad request.
A magnifying glass resting on an antique wooden table
Image: Magnifying glass on antique table,Stéphane Magnenat,CC BY-SA 4.0,via Wikimedia Commons.

An unfilled AdSense slot is an <ins> element whose ad request returned no ad. AdSense marks it with data-ad-status="unfilled" (or "unfill-optimized" when the “Fill empty in-page ads” setting is on), collapses it only if it is outside the viewport, and otherwise leaves a blank box. You can hide those slots with one CSS rule Google documents, or show your own fallback, as long as you never hide units that did serve.

What does data-ad-status tell you?

Google’s article Use the data-ad-status parameter to hide unfilled ad units explains that after an ad unit has finished requesting an ad, AdSense adds data-ad-status to the <ins> element:

Value Meaning
filled “An ad was returned to the ad unit and is now showing.”
unfilled “No ads were returned and the ad unit is empty.”
unfill-optimized No ads were returned and AdSense optimized the unit (only with the “Fill empty in-page ads” setting on)

Do not confuse it with data-adsbygoogle-status, which Google says is “used by our ad code for ads processing purposes”. That attribute tells you the library has processed the slot, not whether an ad came back.

You can see how often slots go unfilled in your reports: Google points to the average coverage metric in AdSense reporting.

What does AdSense do with unfilled units by default?

From the same article: AdSense tries “to either collapse the ad unit or show a blank space”. It collapses only units that will not cause page reflow, “meaning only ad units outside of the viewport are collapsed”. Units in view keep their size and stay blank.

That default protects your layout stability. web.dev’s CLS guide makes the same point from the other side: “Removing the space set aside for elements can cause just as much CLS as inserting content.”

How do I hide unfilled units with CSS?

Google’s documented rule:

ins.adsbygoogle[data-ad-status="unfilled"] {
  display: none !important;
}

It hides the <ins>, but not a wrapper you may have added to reserve space. If your units sit in a wrapper with min-height, collapse the wrapper too:

.ad-slot:has(ins.adsbygoogle[data-ad-status="unfilled"]) {
  display: none;
}

Use this with care on slots visible at load. Collapsing a slot that the user is looking at moves the content below it, which counts as layout shift. A safer split:

  • Top-of-page slots: keep the space, optionally show a neutral placeholder or house content.
  • Slots further down: collapse when unfilled; the request has usually finished before the user scrolls there.

The CLS guide explains how to size reserved space in the first place.

How do I show a house ad instead?

Google’s second example places your own link and image inside the <ins>, hides it by default and shows it only when the slot is unfilled:

<ins class="adsbygoogle"
     style="display:inline-block;width:300px;height:250px"
     data-ad-client="ca-pub-0000000000000000"
     data-ad-slot="1234567890">
  <a href="/newsletter/"><img src="/img/newsletter-300x250.png" width="300" height="250" alt="Subscribe to our newsletter"></a>
</ins>
<script>
     (adsbygoogle = window.adsbygoogle || []).push({});
</script>
ins.adsbygoogle a {
  display: none !important;
}
ins.adsbygoogle[data-ad-status="unfilled"] a {
  display: block;
}

Point the fallback to your own content (newsletter, a related guide, a product of yours). Keep it clearly yours: a house banner styled to look like a Google ad, or labelled in a way that blurs the line, runs into the ad placement policies on content that mimics ads.

How do I react to the status in JavaScript?

Google mentions MutationObserver as the way to detect changes to data-ad-status. A minimal observer that tags the wrapper, so you can style or log it:

const observer = new MutationObserver((mutations) => {
  for (const m of mutations) {
    const ins = m.target;
    const status = ins.getAttribute("data-ad-status");
    const wrapper = ins.closest(".ad-slot");
    if (wrapper && status) wrapper.dataset.adStatus = status;
  }
});

document.querySelectorAll("ins.adsbygoogle").forEach((ins) => {
  observer.observe(ins, { attributes: true, attributeFilter: ["data-ad-status"] });
});

Useful for analytics (count unfilled slots per template) or for automated audits; see Playwright ad-placement audits for checking slot status at scale.

What are the limits of data-ad-status?

Google lists two:

  1. Top window only. The attribute “is only added to ad units that exist on the top window”. Units served through a cross-domain frame do not get it.
  2. Do not load units hidden. Google does not recommend loading ad units hidden and revealing them when the status changes: “If ad units aren’t initially visible on the page, we may not execute the ad request for that ad unit.” Responsive units also need a visible container to calculate their size (responsive behaviour article).

Why do ad slots go unfilled?

Google does not publish a breakdown of unfilled reasons per slot. Work through the usual causes in order:

Check What to look for
Site status Is the site “Ready” in the Sites page? See site status meanings.
Policy center Restricted or disabled ad serving on the site or page
Ad serving limits New or flagged accounts can have limited ad serving
Code Wrong data-ad-client or data-ad-slot, or the head snippet missing
Container Zero width (“No slot size for availableWidth=0” in the console) or a hidden parent
Blocking controls Many blocked categories or advertisers narrow the demand
Demand Some requests simply get no ad, more often for some countries, devices or topics

Occasional unfilled requests are expected. A sudden jump across the whole site points to a status, policy or code change; a pattern on one template points to the container or placement.

Can the ad size itself cause empty slots?

Yes, in two documented ways.

Fixed sizes outside Google’s limits never show. Google’s Guidelines for fixed-sized display ad units state that “any fixed-sized ads that fall outside of the restrictions below won’t appear when placed on a page”:

Restriction Limit
Dimensions over 450px Only one dimension can exceed 450 pixels
Minimum width 120 pixels
Minimum height 50 pixels
Maximum Neither dimension can exceed 1200 pixels

The same page warns that “certain fixed ad sizes, such as a 120x60, might not have any display ad inventory available”. A rare size can leave a slot empty even when it is valid. If you need a fixed size, use a common one, or switch to a responsive unit, which Google recommends for responsive designs anyway.

Responsive units with no width get no ad. When the responsive code measures the slot at zero width, the console shows adsbygoogle.push() error: No slot size for availableWidth=0. Google’s Ad formats FAQ explains that the code sits “inside a parent container that has no explicit width set”, and the fix is to “either set the width of the parent container or make the ad unit fixed size”. This often happens in flex or grid layouts, closed accordions, tabs and off-canvas menus. Google’s responsive behaviour article lists the other container problems.

Note the difference with an unfilled status: a zero-width slot fails before any ad request, so it may never get a data-ad-status value. Check the console as well as the attribute.

How do I track unfilled slots over time?

Two complementary views:

  1. AdSense reports. Google’s data-ad-status article points to the average coverage metric, which reflects how often ad requests return ads. Break it down by ad unit to find the units that fill least, and by country or platform to see whether demand varies.
  2. Your own logs. The MutationObserver above can send one event per slot with the template, slot ID and status. That shows which page types and positions go empty, which reports by ad unit alone do not show if the same unit is reused across templates.

Look for patterns rather than single events. A slot that is occasionally unfilled needs a fallback style; a slot that is unfilled on most views needs a different position, size or unit.

Common mistakes

  • Targeting data-adsbygoogle-status to hide empty slots. It marks processing, not fill. Use data-ad-status.
  • Expecting the CSS rule to hide unfill-optimized units. Google says the technique only works on units AdSense has not optimized.
  • Hiding units that served. The code modification policy does not allow hiding ad units, apart from the documented responsive media query method.
  • Collapsing above-the-fold slots. It trades a blank box for a layout shift.
  • Clicking or reloading to “test” fill. Use preview tools and reports instead of interacting with your own ads.

Frequently asked questions

What does data-ad-status="unfill-optimized" mean?

It means no ad was returned for the unit and AdSense then optimized the empty slot. It only appears when the "Fill empty in-page ads" setting is turned on. Google notes that the CSS technique for hiding unfilled units only works on units AdSense has not optimized, so a rule targeting "unfilled" will not hide them.

Is it against AdSense policy to hide unfilled ad units?

No. Google's own help article shows CSS that applies display: none !important to ins.adsbygoogle[data-ad-status="unfilled"]. What the code modification policy forbids is hiding ad units that serve ads, for example with display: none, apart from the documented responsive media query exception. Hiding an empty slot does not hide an ad.

Why are my ad slots blank on a new site?

Blank slots are normal while a site is not yet ready or approved, while ad serving is limited, or when there is no demand for that request. Check the site status and the Policy center first. If everything is in order, compare the coverage figure in your reports over several days; occasional unfilled requests are expected and are not an error in your code.

Can I show my own banner when AdSense has no ad?

Yes. Google's data-ad-status article shows a house ad: an image link placed inside the ins element, hidden by default with CSS and displayed only when data-ad-status is "unfilled". Make sure the house ad cannot be mistaken for a Google ad and does not imitate ad styling, and do not load units hidden to reveal them later.

Sources

  1. Use the data-ad-status parameter to hide unfilled ad units · Google AdSense Help
  2. Modifications of AdSense ad code · Google AdSense Help
  3. Guidelines for fixed-sized display ad units · Google AdSense Help
  4. Ad formats FAQ · Google AdSense Help
  5. Optimize Cumulative Layout Shift · web.dev