docs(gatsby-image): Add withIEPolyfill documentation (gatsbyjs#12869)

* Update README.md Add instructions for using `gatsby-image/withIEPolyfill` as implemented by gatsbyjs#12681. * Update packages/gatsby-image/README.md Prompt the user to include an alt attribute, even if empty, for accessibility. Co-Authored-By: ooloth <[email protected]> * Add line breaks Trying to guess what issues Prettier is seeing while my computer is away for repairs... * chore: format
ajordanow · Mar 29, 2019 · 44bed4a · 44bed4a
1 parent ab578b6
commit 44bed4a
Showing 1 changed file with 30 additions and 0 deletions.
diff --git a/packages/gatsby-image/README.md b/packages/gatsby-image/README.md
@@ -127,6 +127,31 @@ export const query = graphql`
 
 For other explanations of how to get started with gatsby-image, see this blog post by community member Kyle Gill [Image Optimization Made Easy with Gatsby.js](https://medium.com/@kyle.robert.gill/ridiculously-easy-image-optimization-with-gatsby-js-59d48e15db6e) or this one by Hunter Chang (which also includes some details about changes to gatsby-image for Gatsby v2): [An Intro To Gatsby Image V2](https://codebushi.com/using-gatsby-image/)
 
+## Polyfilling object-fit/object-position for IE
+
+If you'd like to include a polyfill for the [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)/[`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) CSS properties (which [aren't supported](https://caniuse.com/#feat=object-fit) by default in Internet Explorer), import from `gatsby-image/withIEPolyfill` instead:
+
+```jsx
+// Other imports...
+import Img from "gatsby-image/withIEPolyfill"
+
+export default ({ data }) => (
+  <div>
+    <h1>Hello gatsby-image</h1>
+    <Img
+      fixed={data.file.childImageSharp.fixed}
+      objectFit="cover"
+      objectPosition="50% 50%"
+      alt=""
+    />
+  </div>
+)
+
+// GraphQL query...
+```
+
+Importing from `gatsby-image/withIEPolyfill` tells Gatsby to automatically apply the `object-fit-images` polyfill to your image. To make your `object-fit`/`object-position` values work in IE, be sure to use the `objectFit` and `objectPosition` props (rather than the `imgStyle` prop or a CSS or CSS-in-JS solution) so the polyfill will recognize them.
+
 ## Two types of responsive images
 
 There are two types of responsive images supported by gatsby-image.
@@ -327,6 +352,11 @@ You will need to add it in your graphql query as is shown in the following snipp
 | `onError`              | `func`              | A callback that is called when the image fails to load.                                                                     |
 | `Tag`                  | `string`            | Which HTML tag to use for wrapping elements. Defaults to `div`.                                                             |
 | `critical`             | `bool`              | Opt-out of lazy-loading behavior. Defaults to `false`.                                                                      |
+| `objectFit`            | `string`            | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `cover`.          |
+
+|
+| `objectPosition` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `50% 50%`.
+|
 
 ## Image processing arguments