> For the complete documentation index, see [llms.txt](https://docs.realmacsoftware.com/elements-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmacsoftware.com/elements-docs/elements-language/guides/modals-overlays-and-portals.md).
# Modals, Overlays & Portals
An overlay component lives a double life. The trigger — the button or badge the user clicks — belongs exactly where the user dropped the component, deep inside whatever grid, card, or slider they built. The panel it opens belongs somewhere else entirely: layered over the whole page, above everything. This guide walks through the complete anatomy of that split — an inline trigger, a panel teleported to `bodyEnd` with `@portal`, and an open/close signal that travels between them as a window-level event.
{% hint style="success" %}
This guide dissects the **Modal** (`com.realmacsoftware.modal`) and **Modal Close** (`com.realmacsoftware.modalClose`) components from the open-source [Core Pack](/elements-docs/elements-language/dev-resources/open-source-components.md). Open their source alongside this page.
{% endhint %}
## Why Overlays Break Inside the Layout
Render a full-screen panel where the component sits in the document and three CSS mechanisms conspire against you:
* **Ancestor `overflow`** — any ancestor with `overflow: hidden` or `overflow: auto` (sliders, cards, scroll areas) clips your panel to its own box.
* **Ancestor `transform`** — a transformed ancestor (scroll animations, hover effects) becomes the containing block for `position: fixed` descendants, so your "full-screen" panel positions itself relative to a card instead of the viewport.
* **Stacking contexts** — an ancestor with its own `z-index` and stacking context caps your panel's stacking order. No `z-index: 9999` on the panel can escape it; a sibling section later in the page can still paint on top.
You can't control any of this, because in Elements your component gets dropped into layouts you have never seen. The fix is not more CSS — it is moving the panel's markup out of the layout altogether. That is what [`@portal`](/elements-docs/elements-language/component/language/portal.md) does: it transports a section of your template to a fixed page location. For overlays, the destination is `bodyEnd` — the end of the `` element, outside every layout container, where `fixed` positioning and `z-index` behave predictably.
## Anatomy of the Core Modal
The Modal's `templates/index.html` is short enough to read whole, and it splits cleanly into the two halves described above.
### The Inline Trigger
The first half stays inline — it renders wherever the user drops the Modal:
```html
@dropzone("trigger", title: "Trigger")
```
The trigger is a [`@dropzone`](/elements-docs/elements-language/component/language/dropzone.md), so the user decides what opens the modal — a Button, an Image, a line of text. Clicking anywhere in the span dispatches an `open-modal` event carrying this instance's id (more on that handshake below).
The `hooks.js` side wraps the whole component in an Alpine scope and wires up the optional auto-open behaviours:
```javascript
// hooks.source.js (excerpt)
const { id } = rw.node;
rw.setRootElement({
as: "div",
class: classes.wrapper,
args: {
"x-data": `{ open: false, openModal: () => $dispatch('open-modal', { id: '${id}' }) }`,
"x-init": `${
autoOpen
? `setTimeout(() => openModal(), ${autoOpenTime})`
: null
}`,
"x-exit-intent": openOnExitIntent ? "openModal" : null,
id: globalID,
},
});
// …
rw.setProps({
classes,
id,
transitionAttributes,
});
```
Note that both the click handler and the root scope's `openModal()` do the same thing: dispatch `open-modal` with the instance id. Auto-open on page load, after a delay, or on exit intent all reuse the one function. (Helpers like `classnames` and `getAlpineTransitionAttributesMobile` are shared Core Pack utilities bundled into the compiled `hooks.js` at build time — `hooks.source.js` is the authored source.)
### The Teleported Panel
The second half of the template never renders where the component sits. It is wrapped in `@portal("bodyEnd")`, so Elements transports it to the end of ``:
```html
@portal("bodyEnd")
@dropzone("content", title: "Content")
@endportal
```
Walking through it:
* **`@portal("bodyEnd") … @endportal`** — the whole dialog lands at the end of ``. There is deliberately no `includeOnce` here: unlike a shared `