Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adrop.io/llms.txt

Use this file to discover all available pages before exploring further.

Available in Adrop Web SDK 1.2.3 or later.

​
TL;DR

  • The default mode is responsive. Most publishers can leave it as-is.
  • Use fixed only when the ad slot must be pinned to a fixed height by your card/grid design.
  • Express the container’s size intent (height / aspect-ratio) as an inline style — using a CSS class or Tailwind alone is not recommended.

​
Mode Comparison

ModeBehaviorRecommended for
responsive (default)Picks the ad size that fits the container width. If the container has no explicit size intent, the SDK reserves a sensible min-height to prevent content shifting (CLS).General slots that allow dynamic height. Best for both revenue and UX.
fixedStretches the ad to the container height (width:100%; height:100%). Width-based auto-sizing is disabled.Slots whose height is pinned by a card/grid design and would break under responsive.

​
What is CLS?

Cumulative Layout Shift is the phenomenon where content gets pushed down as an ad loads late in the page lifecycle. A button users were about to tap suddenly moves, causing misclicks. It also affects search ranking and ad revenue. The responsive mode reserves space ahead of time to reduce this shift.

​
Which Mode Should I Use?

Keep the default responsive. Opt into fixed only when:
  • Your ad area height is pinned to the pixel by a card/grid design and must not be altered.
  • The slot needs pixel-perfect alignment with adjacent content (e.g. header, sidebar).
If you only want to suppress the empty-to-filled jump, don’t change the mode — follow the recommended container pattern below. The SDK’s auto-reservation handles it.

​
How to Set the Mode

Narrower scope wins. The resolution order is: 
request option > HTML attribute > global config > default ('responsive')

​
1. Per-slot, programmatic (renderAd)

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

​
2. Per-slot, HTML attribute (declarative)

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

​
3. Publisher-wide default

Adrop.observe({
  appId: 'YOUR_APP_ID',
  backfillMode: 'fixed',
})
If unspecified, 'responsive' is applied.
Always express your size intent (height / aspect-ratio) as an inline style. When inline intent is present, the SDK skips auto-reservation and preserves your design. The four inline properties the SDK recognizes as size intent are:
  • height
  • min-height
  • max-height
  • aspect-ratio
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.
<!-- Dynamic-ratio slot: aspect-ratio inline, rest is free -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full max-w-[640px] rounded-xl bg-gray-100 shadow-sm"
     style="aspect-ratio: 300 / 250;"></div>

<!-- Fixed-height slot: height inline -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full bg-gray-50 rounded border"
     style="height: 90px;"></div>

<!-- Leave it to auto-reservation: no size intent -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full max-w-[728px]"></div>

<!-- Pinning size intent through a CSS class (e.g. 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>

<!-- Specifying height / aspect-ratio only through styled-components / CSS module -->
<StyledAdSlot data-adrop-unit="YOUR_UNIT_ID" />
The SDK only detects inline intent — sizes pinned via classes are invisible to it. Auto-reservation may then conflict with your container intent and render unexpectedly.
How to fix (pick one):
  1. 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>
  2. Disable auto-reservation 
    <div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full aspect-[300/250]"></div>

​
Auto-Reservation Behavior (responsive mode)

In responsive mode, the SDK reserves a safe minimum 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 the publisher expresses height or aspect-ratio intent inline, the SDK skips auto-reservation entirely.

​
Upgrading to 1.2.3

Container stateImpact
inline height / aspect-ratio presentNo change (existing behavior preserved)
No size intentEmpty-space jump is reduced via auto-reservation. Ad behavior is unchanged.
Size intent pinned only via CSS class / TailwindAuto-reservation may extend container height — see Not Recommended and fix.
Because the default is responsive, most upgrades are safe with no code changes. To freeze design at the 1.2.1 behavior, restore with a single line of fixed opt-in (global or per-slot).

Banner Ads (React)

Implement banner ads in React

Banner Ads (CDN)

Implement banner ads via CDN

Reference

BackfillMode type definition