---
title: Image
description: Use the Image component for captions, theme-specific sources, click-to-zoom, width constraints, and alignment.
---

Use `Image` when you need more control than basic Markdown image syntax. It supports visible captions, dark mode image variants, click-to-zoom, width constraints, and alignment.

<Callout type="info" title="Use Markdown for simple images">
For straightforward image references without captions or theme-specific sources,
standard Markdown syntax is usually enough. See [Images and videos](/edit-markdown/images-and-videos)
for Markdown and media examples.
</Callout>

<ComponentPreview>
  ```mdx
  <Image
    src="/images/plants.jpg"
    alt="Overhead shot of moody plants"
  >
    Photo by [Nico Knaack](https://unsplash.com/@xoxnk) on
  [Unsplash](https://unsplash.com/photos/background-pattern-JF70XoUqlpQ?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)
  </Image>
  ```
</ComponentPreview>

## Basic usage

### Provide `src` and `alt`

`src` is required. Always include meaningful `alt` text for accessibility.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/plants.jpg"
    alt="Overhead shot of moody plants"
  />
  ```
</ComponentPreview>

<Callout type="tip" title="Write useful alt text">
Describe what is visible and relevant. Good alt text helps accessibility and supports readers using screen readers.
</Callout>

### Add a caption

Add caption content as the children of the `Image` component. Caption content supports Markdown.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/plants.jpg"
    alt="Overhead shot of moody plants"
  >
    Photo by [Nico Knaack](https://unsplash.com/@xoxnk).
  </Image>
  ```
</ComponentPreview>

Use `title` only when you want a browser tooltip/title attribute on the image. It does not render a visible caption.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/plants.jpg"
    alt="Overhead shot of moody plants"
    title="Overhead shot of moody plants"
  />
  ```
</ComponentPreview>

## Dark mode images

Use the object form of `src` when the image itself should change between light and dark mode. The `light` source is required, and `dark` is optional.

<ComponentPreview>
  ```mdx
  <Image
    src={{
      light: "/images/mountain-layers.jpg",
      dark: "/images/nasa.jpg",
    }}
    alt="Decorative image that changes between light and dark mode"
  >
    This image uses a different source in dark mode.

    Light mode photo by [Marek Piwnicki](https://unsplash.com/@marekpiwnicki) on [Unsplash](https://unsplash.com/photos/layered-blue-mountain-ranges-fade-into-the-sky--_OuVFhN5BU).

    Dark mode photo by [Nasa](https://unsplash.com/@nasa) on [Unsplash](https://unsplash.com/photos/earth-rising-over-the-moons-horizon-Y38PSLjc-Fg).
  </Image>
  ```
</ComponentPreview>

<Callout type="info" title="Use one alt text">
Choose `alt` text that works for both image variants. If the light and dark images communicate different information, consider using one consistent image instead.
</Callout>

## Control size and behavior

### Constrain width

Pass `width` in pixels to keep large images from taking too much space.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/surreal_architecture.jpg"
    alt="Surreal architecture framed through a circular opening"
    width={350}
  >
    A constrained image can sit comfortably inside a wider page.

    Photo by [Mehrab Sium](https://unsplash.com/@mehrab_sium) on [Unsplash](https://unsplash.com/photos/arid-landscape-viewed-through-a-circular-window-in-a-cave-WFXNp8G8-7Q)
  </Image>
  ```
</ComponentPreview>

### Align a constrained image

Use `align` to position an image that is narrower than the content column.
Supported values are `left`, `center`, and `right`. Images are centered by
default.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/surreal_architecture.jpg"
    alt="Surreal architecture framed through a circular opening"
    width={350}
    align="left"
  />
  ```
</ComponentPreview>

### Disable click-to-zoom

Set `zoom={false}` when you want the image to remain static.

<ComponentPreview showAllCode>
  ```mdx
  <Image
    src="/images/plants.jpg"
    alt="Overhead shot of moody plants"
    zoom={false}
  >
    This image does not open the zoom overlay.
  </Image>
  ```
</ComponentPreview>

## Props

| Prop | Description | Type | Default |
| --- | --- | --- | ---: |
| `src` | Image source path or URL. Use object form for light and dark mode variants. | `string` or<br />`{ light?: string; dark?: string }` |  |
| `alt` | Alternative text for accessibility. | `string` |  |
| `title` | Browser tooltip/title attribute. This is not a visible caption. | `string` |  |
| `width` | Max rendered width in pixels. | `number` or `string` |  |
| `align` | Alignment for constrained-width images. | `"left"`, `"center"`, or `"right"` | `"center"` |
| `zoom` | Enables click-to-zoom overlay behavior. | `boolean` | `true` |
| children | Optional visible caption content. Supports Markdown. | `Markdown` |  |

## Supported Props Only

`Image` only supports `src`, `alt`, `title`, `width`, `align`, and `zoom`. Use children for the optional caption.
Unsupported props will throw a user-facing validation error.