# Images and embeds
Add screenshots, media-library images, videos, and iframe embeds to Plandalf docs with Mintlify-style MDX patterns.
Source: /docs/components/image-embeds
Last modified: 2026-06-20
Images and embeds should help readers inspect the thing being explained. Use plain Markdown images for simple screenshots, `MediaImage` for tracked Plandalf assets, and `Frame` when media needs a caption, browser chrome, or containment.

## The path


### Use the simplest image form first


    Start with Markdown image syntax or a normal `` tag when the asset already has a stable public path.


### Use tracked media for product screenshots


    Use `MediaImage` or `MediaScreenshot` when the screenshot is registered in the Plandalf media library.


### Wrap inspectable media in Frame


    Use `Frame` for screenshots, videos, and embeds that need captions, hints, or browser-style chrome.


### Keep embeds contained


    Place iframes inside a frame and give them explicit sizing so they cannot create horizontal scroll.


## Markdown image

![Plandalf API docs preview](/images/stacks/api-first/numi-api-docs.png)

```mdx title="markdown-image.mdx"
![Plandalf API docs preview](/images/stacks/api-first/numi-api-docs.png)
```

## Tracked screenshot


  ![The Numi offer editor with checkout and automation controls.](/images/stacks/api-first/numi-offer-editor.png)


```mdx title="tracked-media.mdx"

  ![The Numi offer editor with checkout and automation controls.](/images/stacks/api-first/numi-offer-editor.png)


```

## Embedded preview


```mdx title="iframe-embed.mdx"


```

## Authoring rules


### Image and embed rules


- `Alt text` (required for images):
    Describe the visible product state or diagram. Do not use generic alt text such as `screenshot`.


- `Frame captions` (recommended):
    Use captions when the media explains a UI state, workflow, or API concept.


- `Iframe titles` (required for embeds):
    Every iframe should have a `title` and a constrained width or aspect ratio.


- `Zoom behavior` (DocsImage):
    Markdown images render through `DocsImage` and receive zoom metadata by default. Add `noZoom` when zooming would not help.


## Properties


- `img.src` (string; required):
  Public image URL or path.


- `img.alt` (string; required):
  Accessible image description.


- `img.noZoom` (boolean):
  Disables docs image zoom metadata.


- `MediaImage.id` (string):
  Media library ID for a tracked screenshot or generated asset.


- `iframe.title` (string; required):
  Accessible title for the embedded surface.


## Related


  - [Frames](/docs/components/frames): Add captions and browser chrome around visual material.
  - [Visual context](/docs/components/visual-context): See the full visual component family.
  - [Files](/docs/components/files): Link downloads and static files from docs.