Skip to main content
To display an image, use the <Image> component. It allows displaying either a single image for all themes (src) or one image per light theme (src) and one image for the dark theme (darkSrc).
When an src path points to the SVG image and there is no darkSrc alternative, image colors will be inverted in the dark theme.
Additionally, you can specify the href property, making an image double as a clickable link. When doing so, the target property allows to change the browsing context of the link.
Making an image into a clickable link disables image zoom capabilities.
Finally, to adjust image dimensions in pixels, use height or width properties. By default, all images use 16:9 aspect ratio and set height to 342px and width to 608px.

​
Import

import { Image } from '/snippets/image.jsx';

​
Usage

Show images using the <Image> component. 
import { Image } from '/snippets/image.jsx';

{/* A single image */}
<Image
  src="/resources/images/<IMAGE>"
/>

{/*
  Image with height of 608px (max allowed).
  Its width will be scaled proportionally to set height and vice versa.
*/}
<Image
  src="/resources/images/<IMAGE>"
  height="608"
/>

{/* Image variations for light or dark themes */}
<Image
  src="/resources/images/<IMAGE>"
  darkSrc="/resources/images/<IMAGE_DARK_THEME>"
  />

{/* Image with all properties set */}
<Image
  src="/resources/images/<IMAGE>"
  alt="<ALT_TEXT>"
  darkSrc="/resources/images/<IMAGE_DARK_THEME>"
  darkAlt="<ALT_TEXT_DARK_THEME>"
  href="<CLICKABLE_LINK>"
  target="_blank"
  height="100"
  width={120 + 120}
  />

​
<Image> props

Implementation: image.jsx The <Image> component accepts the following props:

​
src (required)

type: string The image file URL. The file path should be given either relative to the current .mdx file’s location or absolute, assuming the root of the documentation repository is the / directory.
Relative links should NOT use .. in their paths to avoid discovery or security issues.
Image files must be less than 20 MB uncompressed. For larger files, host them on a CDN service like Amazon S3.
Examples:
  • <Image src="<IMAGE>" /> — relative path to an image placed in the same folder as the current .mdx file.
  • <Image src="/resources/images/<IMAGE>" /> — absolute path to an image in the resources/images/ sub-folder.

​
alt

type: string
default: "" The textual replacement for the image. It is mandatory and incredibly useful for accessibility — screen readers read the attribute value out to their users so they know what the image means. Alt text is also displayed on the page if the image can’t be loaded for any reason, such as network errors, content blocking, or link rot. Setting this attribute to an empty string (alt="") indicates that this image is not a key part of the content (it’s decoration or a tracking pixel), and that non-visual browsers may omit it from rendering. Visual browsers will also hide the broken image icon if the alt attribute is empty and the image failed to display. This attribute is also used when copying and pasting the image to text, or saving a linked image to a bookmark. See more: alt attribute on the <img> image embed element, MDN.

​
darkSrc

The value of this property is ignored unless the src property is set.
type: string
default: src value Similar to the src property, but specifies the image file URL for the dark theme only.

​
darkAlt

The value of this property is ignored unless the darkSrc property is set.
type: string
default: alt value Similar to the alt property, but specifies the image file URL for the dark theme only.

​
href

type: string The <a> anchor element wraps the image, making it clickable. The href property is a URL that the clickable image hyperlink points to. See more: href attribute on the <a> anchor element, MDN.

​
target

The value of this property is ignored unless the href property is set.
type: "_self" | "_blank" | "_parent" | "_top" | "_unfencedTop"
default: "_self" The <a> anchor element wraps the image, making it clickable. The target property specifies where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>). The following types have special meanings for where to load the URL:
  • _self: the current browsing context. (Default)
  • _blank: usually a new tab, but users can configure browsers to open a new window instead.
  • _parent: the parent browsing context of the current one. If there is no parent, behaves as _self.
  • _top: the topmost browsing context, i.e., the “highest” context that’s an ancestor of the current one. If there are no ancestors, behaves as _self.
  • _unfencedTop: allows embedded fenced frames to navigate the top-level frame.
See more: target attribute on the <a> anchor element, MDN.

​
height

type: string | number
default: 342 (pixels) The intrinsic height of the image, in pixels. Must be specified without a unit and be within the inclusive range from 9 to 608. If the width property is not set, then the width of the image is adjusted according to the current aspect ratio in respect to the new set height. Examples:
  • <Image src="<IMAGE>" height="100" /> — height of 100 pixels given in a string.
  • <Image src="<IMAGE>" height={50 + 50} /> — also the height of 100 pixels, but given as a number.
See more: height attribute on the <img> image embed element, MDN.

​
width

type: string | number
default: 608 (pixels) The intrinsic width of the image, in pixels. Must be specified without a unit and be within the inclusive range from 9 to 608. If the height property is not set, then the height of the image is adjusted according to the current aspect ratio in respect to the new set width. Examples:
  • <Image src="<IMAGE>" width="100" /> — width of 100 pixels given in a string.
  • <Image src="<IMAGE>" width={50 + 50} /> — also the width of 100 pixels, but given as a number.
See more: width attribute on the <img> image embed element, MDN.