The <Picture> component

Location: /src/components/common/picture/picture.jsx

Image optimization

Please read the image optimization docs before using the <Picture> component!

corgi's built-in <Picture> component allows you to easily use the generated and optimized images from its image optimization step. This component renders a standard HTML <picture> element; with fallback formats, 1x and 2x srcset support, and breakpoint-specific images.

In this article:

• Basic usage
• Breakpoint-spacific images
• Props

Basic usage

Given the source file location of /src/images/defined/logos/my-company-logo-2x.png, we can use the component as shown below.

There are two things to take note of here:

• The src attribute does not expect the -2x suffix in the filename.
• corgi recognizes that the source image is a PNG, and thus generates a WEBP version as well.

<Picture> component usage

import { Picture } from "@local/components/common";

const MyComponent = () => (
  <Picture
    src="logos/my-company-logo.png"
    alt="Description of the company logo."
  />
);

Rendered DOM markup

<picture>
  <source
    srcset="
      /_images/logos/my-company-logo.webp    1x,
      /_images/logos/my-company-logo-2x.webp 2x
    "
    type="image/webp"
  />
  <source
    srcset="
      /_images/logos/my-company-logo.png    1x,
      /_images/logos/my-company-logo-2x.png 2x
    "
    type="image/png"
  />
  <img
    class=""
    alt="Description of the company logo."
    src="/_images/logos/my-company-logo.png"
  />
</picture>

Images for different breakpoints

Providing your source files' names with specific breakpoint suffixes will generate and optimize all the necessary breakpoint-specific versions of your image. The best part? You do not have to change anything about how you use the component—it's all automatic, based on the filenames. The breakpoint suffixes are as follows, and match those of corgi's pre-defined CSS breakpoints:

Available breakpoint suffixes

medium-up
large-up
xlarge-up
xxlarge-up

File tree with breakpoint-specific images

src/
└── images/
    └── defined/
        └── logos/
            ├── my-company-logo-2x.png
            ├── my-company-logo-medium-up-2x.png
            └── my-company-logo-large-up-2x.png

Rendered DOM markup

<picture>
  <source
    media="(min-width: 1024px)"
    srcset="
      /_images/logos/my-company-logo-large-up.webp    1x,
      /_images/logos/my-company-logo-large-up-2x.webp 2x
    "
    width="248"
    height="128"
    type="image/webp"
  />
  <source
    media="(min-width: 1024px)"
    srcset="
      /_images/logos/my-company-logo-large-up.png    1x,
      /_images/logos/my-company-logo-large-up-2x.png 2x
    "
    width="248"
    height="128"
    type="image/png"
  />
  <source
    media="(min-width: 640px)"
    srcset="
      /_images/logos/my-company-logo-medium-up.webp    1x,
      /_images/logos/my-company-logo-medium-up-2x.webp 2x
    "
    width="248"
    height="128"
    type="image/webp"
  />
  <source
    media="(min-width: 640px)"
    srcset="
      /_images/logos/my-company-logo-medium-up.png    1x,
      /_images/logos/my-company-logo-medium-up-2x.png 2x
    "
    width="248"
    height="128"
    type="image/png"
  />
  <source
    srcset="
      /_images/logos/my-company-logo.webp    1x,
      /_images/logos/my-company-logo-2x.webp 2x
    "
    type="image/webp"
    width="248"
    height="128"
  />
  <source
    srcset="
      /_images/logos/my-company-logo.png    1x,
      /_images/logos/my-company-logo-2x.png 2x
    "
    type="image/png"
    width="248"
    height="128"
  />
  <img
    class=""
    alt="Description of the company logo."
    src="/_images/logos/my-company-logo.png"
  />
</picture>

As you can see, this is component is invaluable for working with images!

Props

Prop	Type	Description
src	String	The path to an image, starting from the /src/images/defined/ directory. This should not include the -2x prefix.
alt	String	Alt text attribute for the image.
breakpoints	Array	Optional. Array of breakpoint strings, used for overwriting the default filename-based output. Can include any of: "medium-up", "large-up", "xlarge-up", "xxlarge-up".
lazy	Boolean	Optional. Whether to add browser-native lazy-loading, via the loading="lazy" attribute. Default: false.
className	String	Optional. CSS className to be appended to the rendered <img> element.
pictureClassName	String	Optional. CSS className to be appended to the rendered <picture> element.