# Compass Web SDK: Reserve Space and Handle Empty States

Source: https://dev.arcxp.com/content-recommendations/sdk/reserving-space/

Reserve layout space for an above-the-fold Compass Web SDK component and release it when nothing renders.

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](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/).
- You know which lifecycle events the Experience dispatches. Each Experience dispatches exactly one of `arc-compass:rendered`, `arc-compass:empty`, or `arc-compass:error` per mount, **after the reader has consented**. The events bubble and carry no `detail`. See the lifecycle tables on [Recommendations Components](https://dev.arcxp.com/content-recommendations/sdk/recommendations-components/#loading-empty-and-error)and [Catch Up Card](https://dev.arcxp.com/content-recommendations/sdk/catch-up-card/#lifecycle-and-reserving-space).

## 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:

```html
<div class="rec-slot">
  <arc-compass-recommendations-carousel
    surface-id="homepage-rail"
    heading="Recommended for you"
  ></arc-compass-recommendations-carousel>
</div>
```

```css
.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:

```js
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:empty` is 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:error` means something went wrong and the element is already collapsed. The event doesn’t say why. To find out, see [Nothing renders?](https://dev.arcxp.com/content-recommendations/sdk/troubleshooting/).
- On the Catch Up card, `arc-compass:catchup-done` is 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.

```js
// 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](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/).

## 4\. Test each outcome

Load the page and confirm the slot behaves correctly in each case:

1. **Granted, with content** — the Experience fills the reserved space and the page doesn’t shift.
2. **Granted, nothing to show** — `arc-compass:empty` fires and the slot collapses.
3. **Denied** — your CMP’s denial callback collapses the slot.
4. **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](https://dev.arcxp.com/content-recommendations/sdk/recommendations-components/#a-realistic-integration) — a themed carousel with the reservation and both consent fallbacks wired up.
- [Catch Up Card: A realistic integration](https://dev.arcxp.com/content-recommendations/sdk/catch-up-card/#a-realistic-integration) — the same pattern for the Catch Up card.
- [Compass Web SDK: Nothing Renders?](https://dev.arcxp.com/content-recommendations/sdk/troubleshooting/) — diagnosing a blank Experience.
