feat: add `<PrismicImage>`

[angeloashmore]

Types of changes

• [ ] Chore (a non-breaking change which is related to package maintenance)
• [ ] Bug fix (a non-breaking change which fixes an issue)
• [x] New feature (a non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds a <PrismicImage> component. It renders a Prismic Image field.

<PrismicImage field={imageField} />

This renders the following HTML (using placeholder values for the full image URLs).

<img
  src="https://images.prismic.io/repo/image.png"
  srcset="
    https://images.prismic.io/repo/image.png?width=400   400w,
    https://images.prismic.io/repo/image.png?width=800   800w,
    https://images.prismic.io/repo/image.png?width=1600 1600w
  "
  alt="The field's alt value."
/>

Note that a viewport-width-based srcset is automatically generated. This takes advantage of Imgix's Image URL API which is available to all Prismic users by default.

Note: Prefer using framework-specific image integrations over this component. For example, use Next.js's next/image component or Gatsby's gatsby-plugin-image component if you are using those frameworks. Only use <PrismicImage> if your environment does not have a built-in optimized image component.

Editing images with Imgix

Images can be edited through the image's URL parameters. This includes transformations like saturation, cropping, and blurring.

Arbitrary Imgix parameters can be provided using the imgixParams prop. See Imgix's Image URL API Reference for a full list of what's available.

// Renders grayscale images
<PrismicImage field={imageField} imgixParams={{ sat: -100 }} />

The src URL and each URL in srcset will contain the sat: -100 URL parameter as a result:

https://images.prismic.io/repo/image.png?width=400&sat=-100

Customizing the srcset widths

The widths used in the produced srcset can be controlled using the widths prop. It accepts the following values:

• An array of widths in pixels (e.g. [100, 200, 300])
• "thumbnails" - This will use the Image field's thumbnails (also called responsive views) for each srcset value and its widths.
• "defaults" - Use a good set of defaults (currently [640, 750, 828, 1080, 1200, 1920, 2048, 3840])

// Use the good defaults
<PrismicImage field={imageField} />
<PrismicImage field={imageField} widths="defaults" />

// Use explicit widths
<PrismicImage field={imageField} widths={[100, 200, 300]} />

// Use the Image field's thumbnails for each srcset value
<PrismicImage field={imageField} widths="thumbnails" />

Using pixel density-based srcsets

Pixel density srcsets can also be generated in place of width-based srcsets by using the pixelDensities prop.

<PrismicImage field={imageField} pixelDensities={[1, 2, 3]} />

This renders the following HTML (using placeholder values for the full image URLs).

<img
  src="https://images.prismic.io/repo/image.png"
  srcset="
    https://images.prismic.io/repo/image.png?dpr=1 1x,
    https://images.prismic.io/repo/image.png?dpr=2 2x,
    https://images.prismic.io/repo/image.png?dpr=3 3x
  "
  alt="The field's alt value."
/>

The pixelDensities prop accepts the following values:

• An array of pixel densities (e.g. [2, 4])
• "defaults" - Use a good set of defaults (currently [1, 2, 3])

// Use the good defaults
<PrismicImage field={imageField} pixelDensities="defaults" />

// Use explicit pixel densities
<PrismicImage field={imageField} widths={[2, 4]} />

Checklist:

• [x] My change requires an update to the official documentation.
• [x] All TSDoc comments are up-to-date and new ones have been added where necessary.
• [x] All new and existing tests are passing.

🖼️🦙

[codecov-commenter]

Codecov Report

Merging #140 (e070946) into master (192bdf6) will increase coverage by 0.16%. The diff coverage is 93.93%.

@@            Coverage Diff             @@
##           master     #140      +/-   ##
==========================================
+ Coverage   92.41%   92.58%   +0.16%     
==========================================
  Files          16       18       +2     
  Lines         277      310      +33     
  Branches       62       72      +10     
==========================================
+ Hits          256      287      +31     
  Misses          5        5              
- Partials       16       18       +2     

Impacted Files	Coverage Δ
src/PrismicImage.tsx	93.10% <93.10%> (ø)
src/index.ts	100.00% <100.00%> (ø)
src/lib/devMsg.ts	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 192bdf6...e070946. Read the comment docs.

[github-actions[bot]]

size-limit report 📦

Path	Size
dist/index.js	5.23 KB (+18.91% 🔺)
dist/index.cjs	6.75 KB (+7.13% 🔺)