> For the complete documentation index, see [llms.txt](https://docs.overflowcms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overflowcms.com/api-reference/embed-script-reference.md).

# Embed Script Reference

## Embed Script Reference

### Embed Script Reference

Complete attribute and event reference for `embed.js`. For the narrative walkthrough, see Embed Script Basics (and AI Search & Related Items for the search/related widgets).

#### Script tag

| Attribute       | Where      | Purpose                                                                                                                                |
| --------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `src`           | `<script>` | Always `https://cdn.overflowcms.com/embed.js` — one universal script for every site.                                                   |
| `data-oc-token` | `<script>` | Your site's public token. The script reads the first `<script data-oc-token>` it finds in the document.                                |
| `data-oc-api`   | `<script>` | Optional override for the API base URL (defaults to `https://cdn.overflowcms.com`) — not something you need in a normal Webflow setup. |

#### List container

| Attribute       | Required | Purpose                                                     |
| --------------- | -------- | ----------------------------------------------------------- |
| `data-oc-list`  | Yes      | Collection slug to render.                                  |
| `data-oc-limit` | No       | Items per page; forwarded to the API's `limit` param.       |
| `data-oc-sort`  | No       | Forwarded to the API's `sort` param, e.g. `-publishedDate`. |

While loading, the container carries `data-oc-loading`; on a fetch failure, `data-oc-error` — both are plain attributes you can target in CSS for skeleton/error states.

#### Search container (Pro plan+)

| Attribute              | Required | Purpose                                                                                           |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `data-oc-search`       | Yes      | Collection slug to scope search to; leave the value empty to search every collection on the site. |
| `data-oc-search-input` | Yes      | The `<input>` element the script reads the query from.                                            |
| `data-oc-limit`        | No       | Max results; forwarded to the API's `limit` param.                                                |

Search fires about 250ms after the visitor stops typing, once the query is at least 2 characters — shorter queries clear the results without a request. Uses the same `[data-oc-item]` / `[data-oc-empty]` / `data-oc-loading` / `data-oc-error` contract as a list container.

#### Related items container (Pro plan+)

| Attribute           | Required | Purpose                                                                          |
| ------------------- | -------- | -------------------------------------------------------------------------------- |
| `data-oc-related`   | Yes      | Slug of the collection the *current* item belongs to.                            |
| `data-oc-item-slug` | No       | Overrides the current item's slug. Defaults to the last segment of the page URL. |
| `data-oc-limit`     | No       | Max related items; forwarded to the API's `limit` param.                         |

Fetches once on page load — no debounce, no pagination. Uses the same `[data-oc-item]` / `[data-oc-empty]` / `data-oc-loading` / `data-oc-error` contract as a list container.

#### Inside the item template (`[data-oc-item]`)

| Attribute                     | On                          | Behavior                                                                                                                                                                                                 |
| ----------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-oc-field="<key>"`       | any element                 | Binds the field's value. `<img>` → `src`/`srcset`/`alt`; anything with `data-oc-html` → `innerHTML`; everything else → `textContent`. Supports dotted paths for resolved references, e.g. `author.name`. |
| `data-oc-html`                | paired with `data-oc-field` | Marks the field as HTML content (`innerHTML`) instead of plain text — use for richText fields.                                                                                                           |
| `data-oc-attr-<name>="<key>"` | any element                 | Sets the element's `<name>` attribute to the named field's value (or the item's `slug` if `<key>` is `slug`).                                                                                            |
| `data-oc-link`                | an `<a>`                    | Appends the item's `slug` onto whatever `href` is already there.                                                                                                                                         |

#### Siblings of the item template (inside the list/search/related container, outside `[data-oc-item]`)

| Attribute           | Purpose                                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-oc-empty`     | List/related: shown only when the first (only, for related) page returns zero items. Search: shown when the current query returns zero results. |
| `data-oc-load-more` | A `<button>`, list containers only; fetches the next page and appends. Hidden once there are no more pages.                                     |

#### Events

Both are real, bubbling `CustomEvent`s — listen at `document` level if that's more convenient than the specific node.

| Event              | Dispatched on                     | `detail`                                                                         | When                                                                  |
| ------------------ | --------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `oc:rendered`      | the list/search/related container | `{ page, total }` (list) or `{ query, total }` (search) or `{ total }` (related) | After each render — initial load, "Load more", or a completed search. |
| `oc:item-rendered` | each cloned item node             | `{ item }` (the raw `PublishedItem`)                                             | Once per item, right after its fields are bound.                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.overflowcms.com/api-reference/embed-script-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.