Image

Image with optional placeholder for loading and error state

Import

Source

View source code

Docs

Edit this page

Package

@mantine/core

Usage

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

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>
  );
}

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.

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:

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

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>
  );
}