Skip to content

Commit 02edcdc

Browse files
brimtownGatsbyJS Bot
brimtown
authored and
GatsbyJS Bot
committed
feat(gatsby-image): Add art direction (#13395)
* Add optional media key to PropTypes and Typescript declarations * Add optional fluidImages and fixedImages props * Add art direction to fixed and fluid images * Add art direction to base64 and tracedSVG * Add art direction to noscript image * Add tests for fixedImages and fluidImages * Respond to code review * Use const in tests * Additinal code review refactor * Fix e2e tests * Add README docs * Fix typo and update wording in README * Name selectors in e2e test * Work around SVG bug by encoding spaces * Fix breaking Placeholder change, respond to code review, and update snapshots * Use @polarthene's Pastebin * Update sharp snapshot test * Reset integration tests * Move fluidImages & fixedImages into fluid & fixed * update tests with no media * cleanup spreadprops * Add warning if multiple sources with no media were used * review changes * fix tests
1 parent 784d20f commit 02edcdc

File tree

8 files changed

+490
-84
lines changed

8 files changed

+490
-84
lines changed

‎examples/using-gatsby-image/src/components/floating-image.js

+7-20
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,6 @@ const Image = styled(Img)`
1212
margin-left: ${rhythm(options.blockMarginBottom * 2)};
1313
margin-right: -${gutter.default};
1414
15-
${mq.phablet} {
16-
display: none;
17-
}
18-
`
19-
20-
const ImageDesktop = styled(Image)`
21-
display: none;
22-
23-
${mq.phablet} {
24-
display: block;
25-
}
26-
2715
${mq.tablet} {
2816
margin-right: -${gutter.tablet};
2917
}
@@ -53,15 +41,14 @@ const FloatingImage = ({
5341
https://www.gatsbyjs.org/packages/gatsby-image/#gatsby-image-props
5442
*/}
5543
<Image
56-
fixed={imageMobile}
57-
backgroundColor={backgroundColor ? backgroundColor : false}
58-
style={{ display: `inherit` }}
59-
title={title}
60-
/>
61-
<ImageDesktop
62-
fixed={imageDesktop}
44+
fixed={[
45+
imageMobile,
46+
{
47+
...imageDesktop,
48+
media: mq.phablet.replace(`@media`, ``).trim(),
49+
},
50+
]}
6351
backgroundColor={backgroundColor ? backgroundColor : false}
64-
style={{ display: `inherit` }}
6552
title={title}
6653
/>
6754
</React.Fragment>

‎packages/gatsby-image/README.md

+77-23
Original file line numberDiff line numberDiff line change
@@ -331,31 +331,85 @@ You will need to add it in your graphql query as is shown in the following snipp
331331
}
332332
```
333333

334+
## Art-directing multiple images
335+
336+
`gatsby-image` supports showing different images at different breakpoints, which is known as [art direction](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#Art_direction). To do this, you can define your own array of `fixed` or `fluid` images, along with a `media` key per image, and pass it to `gatsby-image`'s `fixed` or `fluid` props. The `media` key that is set on an image can be any valid CSS media query.
337+
338+
```jsx
339+
import React from "react"
340+
import { graphql } from "gatsby"
341+
import Img from "gatsby-image"
342+
343+
export default ({ data }) => {
344+
// Set up the array of image data and `media` keys.
345+
// You can have as many entries as you'd like.
346+
const sources = [
347+
data.mobileImage.childImageSharp.fluid,
348+
{
349+
...data.desktopImage.childImageSharp.fluid,
350+
media: `(min-width: 768px)`,
351+
},
352+
]
353+
354+
return (
355+
<div>
356+
<h1>Hello art-directed gatsby-image</h1>
357+
<Img fluid={sources} />
358+
</div>
359+
)
360+
}
361+
362+
export const query = graphql`
363+
query {
364+
mobileImage(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) {
365+
childImageSharp {
366+
fluid(maxWidth: 1000, quality: 100) {
367+
...GatsbyImageSharpFluid
368+
}
369+
}
370+
}
371+
desktopImage(
372+
relativePath: { eq: "blog/avatars/kyle-mathews-desktop.jpeg" }
373+
) {
374+
childImageSharp {
375+
fluid(maxWidth: 2000, quality: 100) {
376+
...GatsbyImageSharpFluid
377+
}
378+
}
379+
}
380+
}
381+
`
382+
```
383+
384+
While you could achieve a similar effect with plain CSS media queries, `gatsby-image` accomplishes this using the `<picture>` tag, which ensures that browsers only download the image they need for a given breakpoint.
385+
334386
## `gatsby-image` props
335387

336-
| Name | Type | Description |
337-
| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
338-
| `fixed` | `object` | Data returned from the `fixed` query |
339-
| `fluid` | `object` | Data returned from the `fluid` query |
340-
| `fadeIn` | `bool` | Defaults to fading in the image on load |
341-
| `durationFadeIn` | `number` | fading duration is set up to 500ms by default |
342-
| `title` | `string` | Passed to the `img` element |
343-
| `alt` | `string` | Passed to the `img` element. Defaults to an empty string `alt=""` |
344-
| `crossOrigin` | `string` | Passed to the `img` element |
345-
| `className` | `string` / `object` | Passed to the wrapper element. Object is needed to support Glamor's css prop |
346-
| `style` | `object` | Spread into the default styles of the wrapper element |
347-
| `imgStyle` | `object` | Spread into the default styles of the actual `img` element |
348-
| `placeholderStyle` | `object` | Spread into the default styles of the placeholder `img` element |
349-
| `placeholderClassName` | `string` | A class that is passed to the placeholder `img` element |
350-
| `backgroundColor` | `string` / `bool` | Set a colored background placeholder. If true, uses "lightgray" for the color. You can also pass in any valid color string. |
351-
| `onLoad` | `func` | A callback that is called when the full-size image has loaded. |
352-
| `onStartLoad` | `func` | A callback that is called when the full-size image starts loading, it gets the parameter { wasCached: boolean } provided. |
353-
| `onError` | `func` | A callback that is called when the image fails to load. |
354-
| `Tag` | `string` | Which HTML tag to use for wrapping elements. Defaults to `div`. |
355-
| `objectFit` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `cover`. |
356-
| `objectPosition` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `50% 50%`. |
357-
| `loading` | `string` | Set the browser's native lazy loading attribute. One of `lazy`, `eager` or `auto`. Defaults to `lazy`. |
358-
| `critical` | `bool` | Opt-out of lazy-loading behavior. Defaults to `false`. Deprecated, use `loading` instead. |
388+
| Name | Type | Description |
389+
| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
390+
| `fixed` | `object` / `array` | Data returned from the `fixed` query. When prop is an array it has to be combined with `media` keys, allows for art directing `fixed` images. |
391+
| `fluid` | `object` / `array` | Data returned from the `fluid` query. When prop is an array it has to be combined with `media` keys, allows for art directing `fluid` images. |
392+
| `fadeIn` | `bool` | Defaults to fading in the image on load |
393+
| `durationFadeIn` | `number` | fading duration is set up to 500ms by default |
394+
| `title` | `string` | Passed to the `img` element |
395+
| `alt` | `string` | Passed to the `img` element. Defaults to an empty string `alt=""` |
396+
| `crossOrigin` | `string` | Passed to the `img` element |
397+
| `className` | `string` / `object` | Passed to the wrapper element. Object is needed to support Glamor's css prop |
398+
| `style` | `object` | Spread into the default styles of the wrapper element |
399+
| `imgStyle` | `object` | Spread into the default styles of the actual `img` element |
400+
| `placeholderStyle` | `object` | Spread into the default styles of the placeholder `img` element |
401+
| `placeholderClassName` | `string` | A class that is passed to the placeholder `img` element |
402+
| `backgroundColor` | `string` / `bool` | Set a colored background placeholder. If true, uses "lightgray" for the color. You can also pass in any valid color string. |
403+
| `onLoad` | `func` | A callback that is called when the full-size image has loaded. |
404+
| `onStartLoad` | `func` | A callback that is called when the full-size image starts loading, it gets the parameter { wasCached: boolean } provided. |
405+
| `onError` | `func` | A callback that is called when the image fails to load. |
406+
| `Tag` | `string` | Which HTML tag to use for wrapping elements. Defaults to `div`. |
407+
| `objectFit` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `cover`. |
408+
| `objectPosition` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `50% 50%`. |
409+
| `loading` | `string` | Set the browser's native lazy loading attribute. One of `lazy`, `eager` or `auto`. Defaults to `lazy`. |
410+
| `critical` | `bool` | Opt-out of lazy-loading behavior. Defaults to `false`. Deprecated, use `loading` instead. |
411+
| `fixedImages` | `array` | An array of objects returned from `fixed` queries. When combined with `media` keys, allows for art directing `fixed` images. |
412+
| `fluidImages` | `array` | An array of objects returned from `fluid` queries. When combined with `media` keys, allows for art directing `fluid` images. |
359413

360414
## Image processing arguments
361415

‎packages/gatsby-image/index.d.ts

+4
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ export interface FixedObject {
99
tracedSVG?: string
1010
srcWebp?: string
1111
srcSetWebp?: string
12+
media?: string
1213
}
1314

1415
export interface FluidObject {
@@ -20,13 +21,16 @@ export interface FluidObject {
2021
tracedSVG?: string
2122
srcWebp?: string
2223
srcSetWebp?: string
24+
media?: string
2325
}
2426

2527
interface GatsbyImageProps {
2628
resolutions?: FixedObject
2729
sizes?: FluidObject
2830
fixed?: FixedObject
2931
fluid?: FluidObject
32+
fixedImages?: FixedObject[]
33+
fluidImages?: FluidObject[]
3034
fadeIn?: boolean
3135
title?: string
3236
alt?: string

0 commit comments

Comments
 (0)