--- title: Image description: Add screenshots and diagrams with zoom, captions, and light or dark variants. --- > ## Documentation Index > Fetch the complete documentation index at: https://use.docs.page/llms.txt > Use this file to discover all available pages before exploring further. Display images from remote URLs or files in your repository. Standard Markdown image syntax works and renders through the same `` pipeline as the component. Use `` when you need captions, theme-specific variants, sizing, or explicit zoom control. Use SVG for logos and icons, PNG or WebP for screenshots, and JPEG for photos. ```mdx Dashboard overview ``` ## Markdown images Use standard Markdown syntax for simple images: ```md ![Orange car](https://images.unsplash.com/photo-1671483579112-0872cb05978f?ixlib=rb-4.0.3&auto=format&fit=crop&w=1469&q=80) ``` Markdown images render as `` without extra properties. They inherit zoom behavior from [`content.zoomImages`](/reference/docs-json) in `docs.json` but cannot set `caption`, `theme`, or per-image `zoom` without switching to the component. ![Orange car](https://images.unsplash.com/photo-1671483579112-0872cb05978f?ixlib=rb-4.0.3&auto=format&fit=crop&w=1469&q=80) ## Image sources Pass a full `http` or `https` URL to load an image from that address. Pass a path starting with `/` to load a file from your repository relative to the `/docs` directory. For example, if your repository contains `/docs/assets/my-image.png`, use `/assets/my-image.png` as the `src`. On preview builds (branches, pull requests, or commits), the image is resolved from that Git reference rather than the default branch. ```mdx Pretty picture Remote photo ``` ## Example Orange car ````mdx Orange car ```` ## Properties The image source. External URLs starting with `http` are used as-is. Relative paths such as `/assets/diagram.png` are resolved from the `/docs` directory in your Git repository. On preview builds, repo-relative paths point at the same Git reference as the documentation preview. --- Descriptive alternative text for accessibility. When omitted, the image renders with an empty `alt` attribute. Always provide meaningful `alt` text for informative images. --- Sets the display width in pixels via an inline style. Accepts a number or a numeric string. ```mdx UI screenshot ``` --- Sets the display height in pixels via an inline style. Accepts a number or a numeric string. ```mdx UI screenshot ``` --- Additional CSS classes appended to the default image classes (`mx-auto`, `rounded-lg`). Use this to adjust margins, borders, or responsive layout. ```mdx Product banner ``` --- Controls click-to-zoom behavior for this image. - `zoom={true}`: enables zoom for this image - `zoom={false}`: disables zoom even when [`content.zoomImages`](/reference/docs-json) is `true` in `docs.json` - omitted: follows the global `content.zoomImages` setting (defaults to `false`) ```mdx Detail view ``` --- Renders a centered caption below the image inside a `
` wrapper. ```mdx Abstract shapes ``` --- Restricts visibility to one color scheme. Omit `theme` to show the image in both light and dark modes. - `theme="light"`: visible in light mode only - `theme="dark"`: visible in dark mode only ```mdx Logo Logo ``` ## Zoom Click an image with zoom enabled to open a full-size overlay. Set `zoom` on individual images, or enable zoom site-wide with `content.zoomImages` in `docs.json`. When [`content.zoomImages`](/reference/docs-json) is `true`, all images zoom by default. Pass `zoom={false}` on an `` to opt out for a specific image. Bald eagle in flight ````mdx Bald eagle in flight ```` ## Captions Add `caption` to show descriptive text below the image. The component wraps the image and caption in a `
` element. Abstract shapes ````mdx Abstract shapes ```` ## Theme By default, images appear in both light and dark modes. Set `theme` to show a variant only in the matching color scheme, which is useful for logos or screenshots that do not work on every background. ```mdx Logo Logo ``` ## Additional attributes `` extends the standard HTML `` element. Any attribute not consumed by the properties above (`loading`, `decoding`, `crossOrigin`, `referrerPolicy`, `style`, and others) is forwarded to the underlying ``. The component always sets `loading="lazy"` on the image element. ```mdx Usage chart ``` ## Behavior | Condition | Result | | --- | --- | | `src` starts with `http` | URL used as-is | | `src` is a path such as `/assets/file.png` | Resolved from `/docs` in the repository at the current Git reference | | `zoom={true}` | Click-to-zoom enabled for this image | | `zoom={false}` | Click-to-zoom disabled, even when `content.zoomImages` is `true` | | `zoom` omitted | Follows `content.zoomImages` in `docs.json` (defaults to `false`) | | `caption` set | Image and caption wrapped in `
` with a `
` | | `theme="light"` | Hidden in dark mode | | `theme="dark"` | Hidden in light mode | | Markdown `![alt](url)` syntax | Rendered through `` with the same source and zoom rules | ## See also - [docs.json](/reference/docs-json): `content.zoomImages` and other content settings - [Video](/components/video): self-hosted video (no repo-relative path support) - [Components overview](/components): when to use images, callouts, and embeds