# Images and embeds (/create/image-embeds)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1787 · updated: 2026-07-30 -->
Related: [Changelogs](/create/changelogs.md), [Format code](/create/code.md), [Files](/create/files.md), [Lists and tables](/create/list-table.md), [Personalized content](/create/personalization.md), [Redirects](/create/redirects.md)

Add images, embed videos, and include interactive content with iframes to your documentation.

<Frame>
  <img className="rounded-xl" src="https://mintlify-assets.b-cdn.net/bigbend.jpg" alt="Photograph of a scenic landscape with purple flowers in the foreground, mountains in the background, and a blue sky with scattered clouds." />
</Frame>

## Images [#images]

Add images to provide visual context, examples, or decoration to your documentation.

### Basic image syntax [#basic-image-syntax]

Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add images to your documentation:

```mdx
![Alt text describing the image](/images/screenshot.png)
```

Image paths are root-relative from your docs repository. For example, if your image is at `images/screenshot.png` in your repository, the path is `/images/screenshot.png`. Relative paths (for example, `./screenshot.png`) are not supported.

<Tip>
  Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows.
</Tip>

Image files must be less than 20 MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com).

### HTML image embeds [#html-image-embeds]

For more control over image display, use HTML `<img>` tags:

```jsx
<img 
  src="/images/dashboard.png" 
  alt="Main dashboard interface"
  style={{height: "300px", width: "400px"}}
  className="rounded-lg"
/>
```

#### Resize images with inline styles [#resize-images-with-inline-styles]

Use JSX inline styles with the `style` attribute to resize images:

```jsx
<img
  src="/images/architecture.png"
  style={{width: "450px", height: "auto"}}
  alt="Diagram showing the architecture of the system"
/>
```

#### Disable image zoom [#disable-image-zoom]

To disable the default zoom on click for images, add the `noZoom` property:

```html highlight="4"
<img 
  src="/images/screenshot.png" 
  alt="Descriptive alt text"
  noZoom
/>
```

#### Link images [#link-images]

To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:

```html
<a href="https://mintlify.com" target="_blank">
  <img 
    src="/images/logo.png" 
    alt="Mintlify logo"
    noZoom
  />
</a>
```

<Note>
  Images within anchor tags automatically display a pointer cursor to indicate they are clickable.
</Note>

#### Copy and download actions [#copy-and-download-actions]

Add copy and download controls to an image with the `actions` property. When enabled, buttons appear as an overlay on hover, focus, or touch, letting readers copy the image to their clipboard or save it to their device.

Set `actions` to `true` to show both buttons, or pass a comma-separated list to enable specific actions:

```html
<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions
/>
```

```html
<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions="copy,download"
/>
```

Supported values for `actions`:

* `copy`: Copy the image to the clipboard.
* `download`: Download the image as a file.

Use the `actionsPlacement` property to position the buttons. The default is `bottom-center`.

```html
<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions="download"
  actionsPlacement="top-right"
/>
```

Supported values for `actionsPlacement`: `bottom-center`, `bottom-left`, `bottom-right`, `top-center`, `top-left`, `top-right`.

#### Light and dark mode images [#light-and-dark-mode-images]

To display different images for light and dark themes, use Tailwind CSS classes:

```html
<!-- Light mode image -->
<img 
  className="block dark:hidden" 
  src="/images/light-mode.png" 
  alt="Light mode interface"
/>

<!-- Dark mode image -->
<img 
  className="hidden dark:block" 
  src="/images/dark-mode.png" 
  alt="Dark mode interface"
/>
```

### SVG images [#svg-images]

SVG files that use `foreignObject` elements render differently in production than in local development. Mintlify's image CDN strips `foreignObject` from SVGs as a security measure, which can truncate or hide text and other embedded HTML content.

This commonly affects SVGs exported from tools like [draw.io](https://www.drawio.com) that have HTML text formatting or word wrap turned on. To fix this, disable **Formatted Text** and **Word Wrap** on all labels in your diagram before exporting to SVG. See the [draw.io documentation](https://www.drawio.com/doc/faq/svg-export-text-problems) for more information on SVG exports.

## Videos [#videos]

Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.

<Tip>
  Always include fallback text content within video elements for browsers that don't support video playback.
</Tip>

### YouTube embeds [#youtube-embeds]

Embed YouTube videos using iframe elements:

```html
<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>
```

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/4KzFe50RQkQ" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</Frame>

### Self-hosted videos [#self-hosted-videos]

Use the HTML `<video>` element for self-hosted video content:

```html
<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>
```

### Autoplay videos [#autoplay-videos]

To autoplay a video, use:

```html
<video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video rounded-xl"
  src="/videos/demo.mp4"
></video>
```

<Note>
  When using JSX syntax, write double-word attributes in camelCase: `autoPlay`, `playsInline`, `allowFullScreen`.
</Note>

## Iframes [#iframes]

Embed external content using iframe elements:

```html
<iframe 
  src="https://example.com/embed" 
  title="Embedded content"
  className="w-full h-96 rounded-xl"
></iframe>
```

<Tip>
  Wrap iframes in a [frame](/components/frames) component to keep them within the text column width and prevent overflow.

  ```html
  <Frame>
    <iframe 
      src="https://example.com/embed" 
      title="Embedded content"
      className="w-full h-96 rounded-xl"
    ></iframe>
  </Frame>
  ```
</Tip>

## Related resources [#related-resources]

<Card title="Frame component reference" icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M2 6H22M2 18H22&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M6 22L6 2M18 22V2&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" href="/components/frames">
  Learn how to use the Frame component for presenting images.
</Card>