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
This image contained the meaning of life
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>
);
}

Radius

Radius is applied both to the image and placeholder. Radius has predefined values: xs, sm, md, lg, xl which are defined in theme.radius. Alternatively, you can use a number to set border-radius in px:

<Image radius={0} /> // -> default – image has no radius
<Image radius="lg" /> // -> theme predefined large radius
<Image radius={10} /> // -> { borderRadius: 10 }

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>();
const rootRef = useRef<HTMLDivElement>();
return <Image ref={rootRef} imageRef={imageRef} />;
}

BackgroundImage component

Use BackgroundImage component when you need to display the image below any content. Component sets background-image to given src, background-size to cover and background-position to center. It can be used for cards, hero headers and similar components:

BackgroundImage component can be used to add any content on image. It is useful for hero headers and other similar sections
Radius
xs
sm
md
lg
xl
import { BackgroundImage, Center, Text, Box } from '@mantine/core';
function Demo() {
return (
<Box sx={{ maxWidth: 300 }} mx="auto">
<BackgroundImage
src="https://images.unsplash.com/photo-1419242902214-272b3f66ee7a?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=720&q=80"
radius="sm"
>
<Center p="md">
<Text color="#fff">
BackgroundImage component can be used to add any content on image. It is useful for hero
headers and other similar sections
</Text>
</Center>
</BackgroundImage>
</Box>
);
}