Compass Web SDK: Reserve Space and Handle Empty States
An SDK-rendered Experience never shows a reader a spinner, a skeleton, or an error message. It renders its content, or it renders nothing and collapses to zero height. A collapsed element occupies no space, so it causes no layout shift on its own, and below the fold that is the right default: place the tag and do nothing else.
Above the fold, the shift comes from content that paints after the page loads and pushes everything below it down. This guide reserves space for the Experience and releases it whenever there is nothing to show, so an empty or failed response, or a reader who never consents, leaves no gap.
It applies to every SDK-rendered Experience:
<arc-compass-recommendations-carousel>, <arc-compass-recommendations-list>,
and <arc-compass-catchup-card>.
Before you begin
- The SDK is installed and initialized, and consent is wired up. See Compass Web SDK: Integration Guide.
- You know which lifecycle events the Experience dispatches. Each Experience
dispatches exactly one of
arc-compass:rendered,arc-compass:empty, orarc-compass:errorper mount, after the reader has consented. The events bubble and carry nodetail. See the lifecycle tables on Recommendations Components and Catch Up Card.
1. Wrap the Experience in a slot with a reserved height
Put the tag in a container and give the container a min-height that matches
the Experience’s rendered height on your page:
<div class="rec-slot"> <arc-compass-recommendations-carousel surface-id="homepage-rail" heading="Recommended for you" ></arc-compass-recommendations-carousel></div>.rec-slot { min-height: 320px;}.rec-slot.settled { min-height: 0;}Choose the height per component:
| Experience | Example reservation | Notes |
|---|---|---|
arc-compass-recommendations-carousel | 320px | A single row, so a fixed reservation fits it closely. |
arc-compass-recommendations-list | Measure on your page | Its height depends on how many rows it wraps onto, so a fixed reservation fits it less exactly than it fits the carousel. |
arc-compass-catchup-card | 360px | Adjust to the card’s height with your theme applied. |
2. Release the slot on empty and error
Listen for the two terminal events that mean “nothing to show” and remove the
reservation from the slot that dispatched them. The events bubble, so one
listener on document handles every slot on the page, and event.target tells
you which Experience fired:
document.addEventListener("arc-compass:empty", release);document.addEventListener("arc-compass:error", release);function release(event) { event.target.closest(".rec-slot")?.classList.add("settled");}Release on empty and error only. On rendered, the content is already
filling the slot.
arc-compass:emptyis a successful answer, not a failure: the recommender had nothing for this reader, or the Catch Up card had nothing to catch up on.arc-compass:errormeans something went wrong and the element is already collapsed. The event doesn’t say why. To find out, see Nothing renders?.- On the Catch Up card,
arc-compass:catchup-doneis not a release signal. It describes a reader finishing the takeover, fires later than the terminal event, and may never fire.
3. Release the slot when consent is denied or never answered
The lifecycle events fire only after the reader has consented. An Experience the reader has not consented to renders nothing and dispatches none of the three, so a reader who never grants consent would otherwise be left with a permanent gap. Nothing in the SDK collapses it for you, so handle the two non-granted outcomes yourself:
- Denied — your consent management platform (CMP) reports the decision; collapse the reserved slots from that callback.
- Never answered — the reader ignores the banner, so no callback ever fires. Fall back to a timeout that collapses any slot still reserved.
// Denied: the SDK has no consent-denied event of its own, so define a handler// and wire it to your CMP's denial callback (the exact API differs per CMP).function collapseReservedSlots() { document.querySelectorAll(".rec-slot").forEach((s) => s.classList.add("settled"));}// yourCmp.onDenied(collapseReservedSlots); // ← wire this up to your consent manager
// Never answered: after a grace period, collapse whatever is left — but only// while consent is still *unresolved*. A granted decision (even one whose cards// are still loading) or a denial is already handled above, so bail if the reader// has since answered; otherwise you risk yanking a slot a slow-but-granted render// is about to fill.setTimeout(() => { if (yourCmp.consentAnswered) return; // ← your CMP's "reader has responded" flag document .querySelectorAll(".rec-slot:not(.settled)") .forEach((s) => s.classList.add("settled"));}, 10000);Do not wait for a terminal event before consent resolves. In the denied or never-answered case, it never comes. For how the consent gate works, see Compass Web SDK: Consent & Identity.
4. Test each outcome
Load the page and confirm the slot behaves correctly in each case:
- Granted, with content — the Experience fills the reserved space and the page doesn’t shift.
- Granted, nothing to show —
arc-compass:emptyfires and the slot collapses. - Denied — your CMP’s denial callback collapses the slot.
- Never answered — after the timeout, the slot collapses.
The SDK keeps its diagnostics on the debug channel, so initialize it with
debug: true while you test, and remove it before you ship.
See also
- Recommendations Components: A realistic integration — a themed carousel with the reservation and both consent fallbacks wired up.
- Catch Up Card: A realistic integration — the same pattern for the Catch Up card.
- Compass Web SDK: Nothing Renders? — diagnosing a blank Experience.