---
title: Code components - Responsive images
---

The [drupal-canvas](https://www.npmjs.com/package/drupal-canvas) package
provides an `Image` component for automatic image optimization, responsive
behavior, and modern loading techniques for code components.

The `Image` component is a wrapper around the
[next-image-standalone](https://www.npmjs.com/package/next-image-standalone)
library, preconfigured with a loader to work with the zero-config dynamic image
style in Drupal Canvas.

## Usage

```jsx
import { Image } from 'drupal-canvas';

const MyComponent = ({ photo }) => {
  return (
    <Image
      src={photo.src}
      alt={photo.alt}
      width={photo.width}
      height={photo.height}
    />
  );
};

export default MyComponent;
```

## Props

### Required Props

#### `src`, `alt`, `width` and `height`

##### Using an image prop

Image prop includes all the required props.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
/>
```

##### Static values

Image can also be used with static values but this is not recommended as it will
not result in responsive image variants being generated.

```jsx
<Image
  src="/profile.png"
  alt="Picture of the author"
  width={500}
  height={500}
/>
```

### Optional Props

#### `fill`

A boolean that causes the image to fill the parent element, which is useful when
the width and height are unknown.

The parent element must assign `position: relative`, `position: fixed`, or
`position: absolute` style.

```jsx
<div style={{ position: 'relative', width: '300px', height: '500px' }}>
  <Image
    src={photo.src}
    alt={photo.alt}
    width={photo.width}
    height={photo.height}
    fill
    style={{
      objectFit: 'cover', // cover, contain, none, scale-down, fill
    }}
  />
</div>
```

#### `sizes`

Defines which image sizes to download at different breakpoints. The value of
sizes will affect performance for images using `fill` or those which are styled
to have a responsive size.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>
```

#### `placeholder`

A placeholder to use while the image is loading to improve perceived
performance. Possible values are `empty`, or `data:[dataUrl]`.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  placeholder="blur"
/>
```

#### `style`

Allows passing CSS styles to the underlying image element.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  style={{
    width: '100%',
    height: 'auto',
  }}
/>
```

#### `onLoad`

A callback function that is invoked once the image is completely loaded and the
placeholder is removed.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  onLoad={(e) => console.log(e.target.naturalWidth, e.target.naturalHeight)}
/>
```

#### `onError`

A callback function that is invoked if the image fails to load.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  onError={(e) => console.error('Image failed to load')}
/>
```

#### `loading`

The loading behavior of the image. Defaults to `lazy`.

When `lazy`, defer loading the image until it reaches a calculated distance from
the viewport.

When `eager`, load the image immediately.

```jsx
<Image
  src={photo.src}
  alt={photo.alt}
  width={photo.width}
  height={photo.height}
  loading="eager"
/>
```
