> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed

> Show any web page on a Custral page: a dashboard, a report, a recording.

## Overview

The **Embed** block puts another site's page onto a Custral page. Paste an
`https://` address and it renders in place: a Grafana panel, a Metabase
question, a Looker Studio report, a Loom recording, a Figma board.

The page is sandboxed. It runs in its own origin, it cannot read your workspace,
and it is handed nothing about you: no session, no token, no record.

<Note>
  An Embed block you configure yourself has **no access to Custral data at
  all**. A provider's embed block, installed from an integration, can ask for
  read access, and when it does you are shown exactly what it is asking for
  before it installs.
</Note>

## Configuration parameters

| Param             | Type      | Description                                 |
| ----------------- | --------- | ------------------------------------------- |
| `url`             | `text`    | The `https://` address to show (required).  |
| `allowFullscreen` | `boolean` | Let the page go fullscreen. Off by default. |

## Share links are converted for you

Most services have a page URL you can read and a different one you can embed.
Paste whichever you have. The address from your browser's bar is fine.

| You paste                               | It frames                                       |
| --------------------------------------- | ----------------------------------------------- |
| `youtube.com/watch?v=…` or `youtu.be/…` | The embed player, keeping any `?t=` start time  |
| `loom.com/share/…`                      | `loom.com/embed/…`                              |
| `docs.google.com/spreadsheets/d/…/edit` | The `/preview` view, without the editing chrome |
| `figma.com/design/…`                    | The Figma embed viewer                          |

Anything else is used exactly as you pasted it, query string and fragment
included. That matters more than it sounds: a Grafana panel's `?from` / `?to` /
`?panelId` and a Metabase question's `#` fragment **are** what is being
embedded, so they are never rewritten or dropped.

## Tested URL shapes

| Service       | Shape                                                                          | Fullscreen |
| ------------- | ------------------------------------------------------------------------------ | ---------- |
| Grafana       | `https://grafana.example.com/d-solo/<uid>/<slug>?panelId=4&from=now-6h&to=now` | Not needed |
| Metabase      | `https://metabase.example.com/question#<serialised>`                           | Not needed |
| Looker Studio | `https://lookerstudio.google.com/embed/reporting/<id>/page/<page>`             | Not needed |
| YouTube       | `https://www.youtube.com/watch?v=<id>`                                         | **Yes**    |
| Loom          | `https://www.loom.com/share/<id>`                                              | **Yes**    |
| Figma         | `https://www.figma.com/design/<key>/<name>`                                    | **Yes**    |

Turn `allowFullscreen` on for video and design tools, where a reader will want
the whole screen. Leave it off for dashboards. A panel has nothing to expand
into, and the capability is not granted unless it is asked for.

## What will not embed, and why

| Symptom                                    | Cause                                    | What to do                                                                                                                                                                                |
| ------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "This page can't be shown here"            | The URL is not `https://`                | Embeds must be `https://`. An `http://` page would be sent in the clear, and browsers block it inside a secure page anyway.                                                               |
| "This page can't be shown here"            | It is a Custral address                  | A Custral page cannot be framed inside itself. Link to it instead.                                                                                                                        |
| "This host isn't on your workspace's list" | Your workspace restricts embed hosts     | Ask an admin to add the host in workspace settings, or use one already listed.                                                                                                            |
| The frame stays blank                      | The site refuses to be framed            | Many sites send `X-Frame-Options` or a `frame-ancestors` policy that blocks embedding. Look for a dedicated "embed" or "share" URL (most dashboards have one) or a public/anonymous link. |
| A private dashboard shows a login page     | The frame has its own session, not yours | Sign in to that service in the same browser, or use its published/public link.                                                                                                            |

<Warning>
  A blank frame is almost always the third-party site declining to be embedded.
  Custral cannot detect that from outside the frame (the browser reports a
  refused frame and a successfully-loaded one identically), so the block cannot
  tell you which it was.
</Warning>

## Privacy

* The framed page is told **nothing** about the Custral page it sits on. The
  referrer is stripped, so the service is not sent your workspace's address.
* It cannot navigate your tab away from Custral.
* It cannot read or write your workspace unless it is a provider's embed block
  you explicitly consented to at install.


## Related topics

- [Embed blocks](/dev/embeds/overview.md)
- [Embedded Components](/blocks/embedded/overview.md)
- [Form](/blocks/embedded/object/form.md)
- [Spreadsheet](/blocks/embedded/object/spreadsheet.md)
- [Inbox](/blocks/embedded/object/inbox.md)