Image

Image with optional placeholder for error state

Import

Source

View source code

Docs

Edit this page

Package

@asuikit/core

Usage

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

import { Image } from '@asuikit/core';

function Demo() {
  return (
    <Image maw={240} mx="auto" radius="md" src="./avatar.png" alt="Random image" />
  );
}

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 '@asuikit/core';

function Demo() {
  return (
    <>
      {/* By default image will have object-fit: cover */}
      <Image width={200} height={80} src="./image.png" />

      {/* 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="./image.png" />

      {/* It's not necessary to use both width and height */}
      <Image height={80} src="./image.png" />
    </>
  );
}

Placeholder

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

withPlaceholder prop is set to true
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, Group } from '@asuikit/core';

function Demo() {
  return (
    <Group position="center">
      <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>}
      />
    </Group>
  );
}

With caption

You can add figcaption to an image with caption prop:

import { Image, Box } from '@asuikit/core';

function Demo() {
  return (
    <Box maw={240} mx="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"
      />
    </Box>
  );
}

Get refs

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

import { useRef } from 'react';
import { Image } from '@asuikit/core';

function Demo() {
  const imageRef = useRef<HTMLImageElement>(null);
  const rootRef = useRef<HTMLDivElement>(null);
  return <Image ref={rootRef} imageRef={imageRef} />;
}

Go back

ColorSwatch – @asuikit/core

Up next

Indicator – @asuikit/core

Image component props

Name	Type	Description
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	Omit<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "ref">	Props spread to img element
imageRef	ForwardedRef<HTMLImageElement>	Get image element ref
placeholder	ReactNode	Customize placeholder content
radius	number \| "xs" \| "sm" \| "md" \| "lg" \| "xl"	Key of theme.radius or any valid CSS value to set border-radius, 0 by default
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

Name	Static selector	Description
root	.asuikit-Image-root	Root element
imageWrapper	.asuikit-Image-imageWrapper	Wraps image and placeholder
placeholder	.asuikit-Image-placeholder	Placeholder wrapper
figure	.asuikit-Image-figure	figure element, wrap image and figcaption
image	.asuikit-Image-image	img element
caption	.asuikit-Image-caption	figcaption element