---
title: Ad Data Source
slug: experience/ad-data-source
docTags: 
createdAt: 2026-05-11T12:15:15.996Z
---

## Overview

The `ad` data source loads ad slot definitions from `ads.json` and makes them available as list items. Unlike the `ad` insertion property (which interleaves ads into another data source's results), this data source is used when a component is dedicated entirely to rendering ad slots — for example, a list of banner ads or a swiper of ad creatives.

## When to use this

Use `ad` when a component's sole purpose is to display ads from `ads.json`. For inserting ads between content items in a mixed list, use the `ad` insertion property on the content data source instead.

For more details on ad insertion between content items, see: [Embedded ads in Experience](docId\:fBXEGKJkrGezHEwjHksd1)

## Basic Example

```json
{
  "type": "ad",
  "contextKey": "banners",
  "idPattern": "sidebar-banner"
}
```

This loads all ad slot definitions from `ads.json` whose `id` matches the pattern `sidebar-banner`, and exposes them as `$context.banners`. A child component renders the ad creative using the slot's configuration.

## Configuration

### Type-specific properties

| Property  | Type   | Default | Description                                                                                                                                            |
| --------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| idPattern | string | —       | Optional regex pattern to filter ad slots by their `id` field. Only ads whose `id` matches the pattern are returned. If omitted, all ads are returned. |

### Common configuration (inherited)

All common data source properties apply — `contextKey`, `limit`, etc.

For more details, see [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)

## Advanced Features

### Filtering by pattern

Use `idPattern` to restrict which ad slots are loaded. The value is a JavaScript regex pattern tested against each ad slot's `id`:

```json
{
  "type": "ad",
  "contextKey": "banners",
  "idPattern": "^sidebar-"
}
```

This loads all ad slots whose `id` starts with `sidebar-` (e.g., `sidebar-banner`, `sidebar-promo`).

### Conditional ad loading

The `ad` data source supports a `condition` value to enable or disable ad loading at runtime — for example, to suppress ads for subscribed users:

```json
{
  "type": "ad",
  "contextKey": "promoAd",
  "idPattern": "promo-banner",
  "condition": {
    "value": "$context.user.isSubscriber",
    "operation": "EQUALS",
    "compareValue": "false"
  }
}
```

For more details on conditions, see:
[TODO insert link to Conditions](#)

## Testing Notes / Edge Cases

- `idPattern`** is a regex**: The value is compiled with `new RegExp(idPattern)` and tested against each ad slot's `id`. An invalid regex logs a warning and falls back to returning all ad slots unfiltered.
- **No **`idPattern`** returns all slots**: If `idPattern` is omitted, the data source returns all ad slots defined in `ads.json` (subject to `limit` and element-level conditions).
- **Ad vs. ad insertion**: This data source is for ad-only components. Do not confuse it with the `ad` property on other data sources, which inserts ads between content items. Using both on the same component leads to duplicate ad slots.
- **Condition-based suppression**: When a data-source-level condition evaluates to false, the data source returns an empty list. Ensure the parent component handles the empty state without breaking the layout.
- **Context-reactive filtering**: The data source re-evaluates element-level conditions whenever the view context changes. If the filtered result differs, the component updates automatically.
- **No SSR data**: The ad data source does not restore data from SSR — it always fetches from the store on the client.

## Related Topics

- [TODO insert link to Data Sources Overview](#)
- [TODO insert link to Ad Insertion](#)
- [TODO insert link to Conditions](#)