Image

Image with optional placeholder for loading and error state
Import

Usage

Image component is a wrapper around img element with option to change object fit, radius and placeholder:

Random unsplash image
import { Image } from '@mantine/core';
function Demo() {
return (
<div style={{ width: 240, marginLeft: 'auto', marginRight: 'auto' }}>
<Image
radius="md"
src="https://images.unsplash.com/photo-1511216335778-7cb8f49fa7a3?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=720&q=80"
alt="Random unsplash image"
/>
</div>
);
}

Width and height

In the example above, the image takes 100% of the width of its container and height is calculated dynamically based on image proportion. To change this behavior, set image width and height to define image size.

Note that if image proportions do not match the given width and height, some parts will be cut out. In case you want to show the image with its original proportions and want it to fit in the current width and height, set fit="contain":

import { Image } from '@mantine/core';
function Demo() {
return (
<>
{/* By default image will have object-fit: cover */}
<Image
width={200}
height={80}
src="https://images.unsplash.com/long-image-url-was-here.jpg"
/>
{/* Set fit="contain" to preserve image proportions in this case image wrapper will still have given width and height */}
<Image
width={200}
height={80}
fit="contain"
src="https://images.unsplash.com/long-image-url-was-here.jpg"
/>
{/* It's not necessary to use both width and height */}
<Image
height={80}
src="https://images.unsplash.com/long-image-url-was-here.jpg"
/>
</>
);
}

Placeholder

By default, image placeholders are disabled. Image placeholder is displayed in these cases:

  • withPlaceholder prop is set to true
  • Image is currently loading
  • Error occurred during image loading (e.g. broken link)
  • Image did not receive src prop

To customize image placeholder pass any react node to placeholder prop. Placeholder size is determined by width and height props. Placeholder is centered vertically and horizontally across provided width and height.

Without placeholder
With default placeholder
With custom placeholder
import { Image, Text } from '@mantine/core';
function Demo() {
return (
<>
<Image
width={200}
height={120}
src={null}
alt="Without placeholder"
/>
<Image
width={200}
height={120}
src={null}
alt="With default placeholder"
withPlaceholder
/>
<Image
height={120}
width={200}
src="42.png"
alt="With custom placeholder"
withPlaceholder
placeholder={<Text align="center">This image contained the meaning of life</Text>}
/>
</>
);
}

With caption

You can add figcaption to an image with caption prop:

Random unsplash image
My dog begging for treats
import { Image } from '@mantine/core';
function Demo() {
return (
<div style={{ width: 240, marginLeft: 'auto', marginRight: 'auto' }}>
<Image
radius="md"
src="https://images.unsplash.com/photo-1627552245715-77d79bbf6fe2?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=640&q=80"
alt="Random unsplash image"
caption="My dog begging for treats"
/>
</div>
);
}

Get refs

You can get both image and root element (div) refs with ref and imageRef props:

import { useRef } from 'react';
import { Image } from '@mantine/core';
function Demo() {
const imageRef = useRef<HTMLImageElement>(null);
const rootRef = useRef<HTMLDivElement>(null);
return <Image ref={rootRef} imageRef={imageRef} />;
}
Download more icon variants from https://tabler-icons.io/i/search

Image component props

NameTypeDescription
alt
string
Image alt text, used as title for placeholder if image was not loaded
caption
ReactNode
Image figcaption, displayed below image
fit
"contain" | "fill" | "-moz-initial" | "inherit" | "initial" | "revert" | "unset" | "none" | "cover" | "scale-down"
Image object-fit property
height
string | number
Image height, defaults to original image height adjusted to given width
imageProps
Pick<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "key" | keyof ImgHTMLAttributes<...>>
Props spread to img element
imageRef
ForwardedRef<HTMLImageElement>
Get image element ref
placeholder
ReactNode
Customize placeholder content
radius
number | "xs" | "sm" | "md" | "lg" | "xl"
Predefined border-radius value from theme.radius or number for border-radius in px
src
string
Image src
width
string | number
Image width, defaults to 100%, cannot exceed 100%
withPlaceholder
boolean
Enable placeholder when image is loading and when image fails to load

Image component Styles API

NameStatic selectorDescription
root.mantine-Image-rootRoot element
imageWrapper.mantine-Image-imageWrapperWraps image and placeholder
placeholder.mantine-Image-placeholderPlaceholder wrapper
figure.mantine-Image-figurefigure element, wrap image and figcaption
image.mantine-Image-imageimg element
caption.mantine-Image-captionfigcaption element