Backfill Rendering Mode

Available in Adrop Web SDK 1.2.3 or later.

TL;DR

For most slots, copy this pattern:

<!-- Mobile-friendly 320×100 banner slot -->
<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-backfill-mode="fixed"
  style="width: 100%; aspect-ratio: 320 / 100;"
></div>

This single pattern gives you:

Responsive width — the slot fills the device width on any screen
Locked height — aspect-ratio derives the height from the width, so no CLS
Predictable rendering — fixed mode stretches the backfill ad to the container exactly

The two ingredients are backfillMode: fixed and aspect-ratio (inline) matching the registered unit size (320/100, 300/250, 728/90, …).

Prerequisite: this snippet assumes Adrop.observe({ appId: 'YOUR_APP_ID' }) has been called somewhere on the page. While developing, replace YOUR_UNIT_ID with PUBLIC_TEST_UNIT_ID_320_100 to see a live test ad. For SDK install and initialization, see the Banner Ads or CDN guides.

When to Use Which Mode

Mode	Behavior	Use it when
`fixed`	Stretches the backfill ad to fill the container (`width:100%; height:100%`). The publisher defines the slot size — by `aspect-ratio` for responsive width, or `height` for pixel-pinned slots.	You know the slot’s size or ratio and want the ad to fit exactly. Recommended for most banner slots.
`responsive` (default)	The backfill network picks the ad size that best fits the container width. The SDK reserves a safe `min-height` automatically if the container has no size intent.	You don’t want to commit to a size up front. The network gets the widest pick from its inventory.

Both modes are CLS-safe when the container has an inline size intent (aspect-ratio, height, min-height, or max-height). The difference is whether the publisher or the network decides the height.

fixed mode follows the container’s height directly. If the container has no aspect-ratio or height defined, the ad collapses to 0px and becomes invisible — always pair fixed with a height intent.

Container Patterns

Pick the pattern that matches your slot. All three work with both direct and backfill ads.

Pattern A. Responsive width + locked ratio (recommended)

The slot fills the available horizontal width, and aspect-ratio derives the height from the unit’s registered size. Best for mobile-first layouts and content feeds.

<!-- 320 × 100 mobile banner ratio -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 320 / 100;"></div>

<!-- 300 × 250 medium rectangle ratio -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 300 / 250;"></div>

<!-- 728 × 90 leaderboard ratio -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 728 / 90;"></div>

Use the aspect-ratio that matches the unit’s registered size. The container’s height is width × (ratio.h / ratio.w), and fixed mode tells the SDK to fill that exact box.

If you need to cap the width, base the cap on your own design (content column, sidebar width, etc.) — not on the registered ad size. Pinning max-width to the registered pixel size shrinks the ad on wider screens and reduces revenue. As long as the ratio is preserved, the backfill ad fills the container at any width.

Pattern B. Fixed pixel height (pixel-precise alignment)

Use this when the slot must align pixel-by-pixel with other content (a docked header, sidebar, sticky footer).

<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; height: 100px;"></div>

Pattern C. SDK auto-reservation (no size committed)

Use this when you don’t want to commit to a size — the SDK reserves a safe min-height based on the container width to keep CLS low, and the backfill network picks the best inventory match.

<div data-adrop-unit="YOUR_UNIT_ID"
     style="width: 100%;"></div>

This is the default behavior. No data-adrop-backfill-mode attribute needed.

Specifying the Mode

The narrowest scope wins:

request option > HTML attribute > global config > default ('responsive')

Per-slot (declarative)

<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 320 / 100;"></div>

Per-slot (programmatic)

await Adrop.instance().renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  backfillMode: 'fixed',
})

Publisher-wide default

Adrop.observe({
  appId: 'YOUR_APP_ID',
  backfillMode: 'fixed',
})

Size Intent Must Be Inline

The SDK reads only these four inline properties as size intent:

height
min-height
max-height
aspect-ratio

If any of them is present inline, the SDK preserves the publisher’s layout and skips auto-reservation.

All other styles — width, padding, margin, color, border, shadow, transition, etc. — can use CSS classes or Tailwind freely. Only those four size-intent properties need to be inline.

<!-- aspect-ratio inline, everything else via class -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full max-w-[640px] rounded-xl bg-gray-100 shadow-sm"
     style="aspect-ratio: 300 / 250;"></div>

<!-- height inline, everything else via class -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full bg-gray-50 rounded border"
     style="height: 90px;"></div>

Not Recommended

<!-- Size intent pinned only through CSS class / Tailwind -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full aspect-[300/250] rounded-xl"></div>

<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full h-[100px]"></div>

<!-- Size intent only via styled-components / CSS module -->
<StyledAdSlot data-adrop-unit="YOUR_UNIT_ID" />

The SDK cannot see sizes pinned through CSS classes. In responsive mode, auto-reservation runs in parallel with the class-driven height and may extend the container beyond what you intended.

How to fix (pick one):

Move size intent to inline style (recommended)

<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full rounded-xl"
     style="aspect-ratio: 300 / 250;"></div>

Opt into fixed to disable auto-reservation

<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full aspect-[300/250]"></div>

CLS and Auto-Reservation

What is CLS? Cumulative Layout Shift happens when a late-arriving ad pushes the rest of the content down. A button users were about to tap suddenly moves, causing misclicks. It also affects search ranking and ad revenue. How responsive mode handles it: when the container has no inline size intent, the SDK reserves a safe min-height based on the container width.

If the actual ad is larger than the reserved value, the container expands naturally (the jump is just smaller).
If the actual ad is smaller, the empty space remains (no jump occurs).
Only min-height is set — never max-height — so there is no overflow risk.

If you express height or aspect-ratio inline, the SDK skips auto-reservation entirely — your layout wins.

Auto-Refresh

Once a backfill ad loads successfully, the SDK manages refresh automatically — you don’t need to configure or call anything.

Visibility-gated: refresh counts only while the container is at least 50% visible and the page tab is active
Bounded: refreshes stop after a fixed maximum count per slot
Self-cleaning: when the container is removed from the DOM, refresh is unregistered automatically

Every successful refresh fires an AD_RECEIVED event with format: 'backfill'.

When No Backfill Is Available

If neither a direct ad nor a backfill ad can be served, the SDK emits the AD_BACKFILL_NO_FILL event. Listen for it to hide the slot or render fallback content.

Adrop.instance().on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {
  // Hide the slot or render fallback content
})

For the full event lifecycle, see the Banner Ads guide.

Upgrading to 1.2.3

Container state	Impact
Inline `height` / `aspect-ratio` present	No change (existing behavior preserved)
No size intent	Empty-space jump is reduced via auto-reservation. Ad behavior unchanged.
Size intent only via CSS class / Tailwind	Action required — auto-reservation may extend the container. Before upgrading, see Not Recommended and either move the intent inline or opt into `fixed`.

The default mode is responsive, so most upgrades are safe with no code change. To freeze the pre-1.2.3 layout, add a single fixed opt-in (globally or per-slot).

Banner Ads (React)

Implement banner ads in React

Banner Ads (CDN)

Implement banner ads via CDN

Reference

BackfillMode type definition

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

TL;DR

When to Use Which Mode

Container Patterns

Pattern A. Responsive width + locked ratio (recommended)

Pattern B. Fixed pixel height (pixel-precise alignment)

Pattern C. SDK auto-reservation (no size committed)

Specifying the Mode

Size Intent Must Be Inline

Recommended

Not Recommended

CLS and Auto-Reservation

Auto-Refresh

When No Backfill Is Available

Upgrading to 1.2.3

Banner Ads (React)

Banner Ads (CDN)

Reference

​TL;DR

​When to Use Which Mode

​Container Patterns

​Pattern A. Responsive width + locked ratio (recommended)

​Pattern B. Fixed pixel height (pixel-precise alignment)

​Pattern C. SDK auto-reservation (no size committed)

​Specifying the Mode

​Size Intent Must Be Inline

​Recommended

​Not Recommended

​CLS and Auto-Reservation

​Auto-Refresh

​When No Backfill Is Available

​Upgrading to 1.2.3

​Related Guides

Banner Ads (React)

Banner Ads (CDN)

Reference

TL;DR

When to Use Which Mode

Container Patterns

Pattern A. Responsive width + locked ratio (recommended)

Pattern B. Fixed pixel height (pixel-precise alignment)

Pattern C. SDK auto-reservation (no size committed)

Specifying the Mode

Size Intent Must Be Inline

Recommended

Not Recommended

CLS and Auto-Reservation

Auto-Refresh

When No Backfill Is Available

Upgrading to 1.2.3

Related Guides