Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
gatsby-image
Advanced tools
gatsby-image - npm Package Compare versions
Comparing version 1.0.26 to 1.0.27
| { | ||
| "name": "gatsby-image", | ||
| "version": "1.0.26", | ||
| "version": "1.0.27", | ||
| "description": "Lazy-loading React image component with optional support for the blur-up effect.", | ||
@@ -5,0 +5,0 @@ "main": "index.js", |
128
README.md
@@ -5,3 +5,7 @@ # gatsby-image | ||
| `gatsby-image` is a React component specially designed to work seamlessly with Gatsby's GraphQL queries. It combines [Gatsby's native image processing](https://image-processing.gatsbyjs.org/) capabilities with advanced image loading techniques to easily and completely optimize image loading for your sites. | ||
| `gatsby-image` is a React component specially designed to work seamlessly with | ||
| Gatsby's GraphQL queries. It combines | ||
| [Gatsby's native image processing](https://image-processing.gatsbyjs.org/) | ||
| capabilities with advanced image loading techniques to easily and completely | ||
| optimize image loading for your sites. | ||
@@ -14,14 +18,21 @@ **[Demo](https://using-gatsby-image.gatsbyjs.org)** | ||
| But creating optimized images for websites has long been a thorny problem. Ideally you would: | ||
| But creating optimized images for websites has long been a thorny problem. | ||
| Ideally you would: | ||
| * Resize large images to the size needed by your design | ||
| * Generate multiple smaller images so smartphones and tablets don't download desktop-sized images | ||
| * Generate multiple smaller images so smartphones and tablets don't download | ||
| desktop-sized images | ||
| * Strip all unnecessary metadata and optimize JPEG and PNG compression | ||
| * Efficiently lazy load images to speed initial page load and save bandwidth | ||
| * Use the "blur-up" technique or a "[traced placeholder](https://github.com/gatsbyjs/gatsby/issues/2435)" SVG to show a preview of the image while it loads | ||
| * Use the "blur-up" technique or a | ||
| "[traced placeholder](https://github.com/gatsbyjs/gatsby/issues/2435)" SVG to | ||
| show a preview of the image while it loads | ||
| * Hold the image position so your page doesn't jump while images load | ||
| Doing this consistantly across a site feels like sisyphean labor. You manually optimize your images and then… several images are swapped in at the last minute or a design-tweak shaves 100px of width off your images. | ||
| Doing this consistantly across a site feels like sisyphean labor. You manually | ||
| optimize your images and then… several images are swapped in at the last minute | ||
| or a design-tweak shaves 100px of width off your images. | ||
| Most solutions involve a lot of manual labor and bookkeeping to ensure every image is optimized. | ||
| Most solutions involve a lot of manual labor and bookkeeping to ensure every | ||
| image is optimized. | ||
@@ -32,11 +43,15 @@ This isn't ideal. Optimized images should be easy and the default. | ||
| With Gatsby, we can make images way *way* better. | ||
| With Gatsby, we can make images way _way_ better. | ||
| `gatsby-image` is designed to work seamlessly with Gatsby's native image processing capabilities powered by GraphQL and Sharp. To produce | ||
| perfect images, you need only: | ||
| `gatsby-image` is designed to work seamlessly with Gatsby's native image | ||
| processing capabilities powered by GraphQL and Sharp. To produce perfect images, | ||
| you need only: | ||
| 1) Import `gatsby-image` and use it in place of the built-in `img` | ||
| 2) Write a simple GraphQL query using one of the included GraphQL "fragments" which specify the fields needed by `gatsby-image`. | ||
| 1. Import `gatsby-image` and use it in place of the built-in `img` | ||
| 2. Write a simple GraphQL query using one of the included GraphQL "fragments" | ||
| which specify the fields needed by `gatsby-image`. | ||
| The GraphQL query creates multiple thumbnails with optimized JPEG and PNG compression. The `gatsby-image` component automatically sets up the "blur-up" effect as well as lazy loading of images further down the screen. | ||
| The GraphQL query creates multiple thumbnails with optimized JPEG and PNG | ||
| compression. The `gatsby-image` component automatically sets up the "blur-up" | ||
| effect as well as lazy loading of images further down the screen. | ||
@@ -46,4 +61,4 @@ This is what a component using `gatsby-images` looks like. | ||
| ```jsx | ||
| import React from 'react' | ||
| import Img from 'gatsby-image' | ||
| import React from "react" | ||
| import Img from "gatsby-image" | ||
@@ -59,3 +74,3 @@ export default ({ data }) => ( | ||
| query GatsbyImageSampleQuery { | ||
| file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg"}) { | ||
| file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) { | ||
| childImageSharp { | ||
@@ -77,20 +92,34 @@ # Specify the image processing steps right in the query | ||
| 1) Images that have a *fixed* width and height | ||
| 2) Images that stretch across a fluid container | ||
| 1. Images that have a _fixed_ width and height | ||
| 2. Images that stretch across a fluid container | ||
| In the first scenario, you want to vary the image's size for different screen *resolutions* -- in other words, create retina images. | ||
| In the first scenario, you want to vary the image's size for different screen | ||
| _resolutions_ -- in other words, create retina images. | ||
| For the second scenario, you want to create multiple *sizes* of thumbnails for devices with widths stretching from smartphone to wide desktop monitors. | ||
| For the second scenario, you want to create multiple _sizes_ of thumbnails for | ||
| devices with widths stretching from smartphone to wide desktop monitors. | ||
| To decide between the two, ask yourself: "do I know the exact size this image will be?" If yes, it's the first type. If no and its width and/or height need to vary depending on the size of the screen, then it's the second type. | ||
| To decide between the two, ask yourself: "do I know the exact size this image | ||
| will be?" If yes, it's the first type. If no and its width and/or height need to | ||
| vary depending on the size of the screen, then it's the second type. | ||
| In Gatsby's GraphQL implementation, you query for the first type by querying a child object of an image called `resolutions` — which you can see in the sample component above. For the second type, you do a similar query but for a child object called `sizes`. | ||
| In Gatsby's GraphQL implementation, you query for the first type by querying a | ||
| child object of an image called `resolutions` — which you can see in the sample | ||
| component above. For the second type, you do a similar query but for a child | ||
| object called `sizes`. | ||
| ## Fragments | ||
| GraphQL includes a concept called "query fragments". Which, as the name suggests, are a part of a query that can be used in multiple queries. To ease building with `gatsby-image`, Gatsby image processing plugins which support `gatsby-image` ship with fragments which you can easily include in your queries. | ||
| GraphQL includes a concept called "query fragments". Which, as the name | ||
| suggests, are a part of a query that can be used in multiple queries. To ease | ||
| building with `gatsby-image`, Gatsby image processing plugins which support | ||
| `gatsby-image` ship with fragments which you can easily include in your queries. | ||
| Note, [due to a limitation of GraphiQL](https://github.com/graphql/graphiql/issues/612), you can not currently use these fragments in the GraphiQL IDE. | ||
| Note, | ||
| [due to a limitation of GraphiQL](https://github.com/graphql/graphiql/issues/612), | ||
| you can not currently use these fragments in the GraphiQL IDE. | ||
| Plugins supporting `gatsby-image` currently include [gatsby-transformer-sharp](/packages/gatsby-transformer-sharp/) and [gatsby-source-contentful](/packages/gatsby-source-contentful/). | ||
| Plugins supporting `gatsby-image` currently include | ||
| [gatsby-transformer-sharp](/packages/gatsby-transformer-sharp/) and | ||
| [gatsby-source-contentful](/packages/gatsby-source-contentful/). | ||
@@ -121,7 +150,14 @@ Their fragments are: | ||
| If you don't want to use the blur-up effect, choose the fragment with `noBase64` at the end. If you want to use the traced placeholder SVGs, choose the fragment with `tracedSVG` at the end. | ||
| If you don't want to use the blur-up effect, choose the fragment with `noBase64` | ||
| at the end. If you want to use the traced placeholder SVGs, choose the fragment | ||
| with `tracedSVG` at the end. | ||
| If you want to automatically use WebP images when the browser supports the file format, use the `withWebp` fragments. If the browser doesn't support WebP, `gatsby-image` will fall back to the default image format. | ||
| If you want to automatically use WebP images when the browser supports the file | ||
| format, use the `withWebp` fragments. If the browser doesn't support WebP, | ||
| `gatsby-image` will fall back to the default image format. | ||
| _Please see the [gatsby-plugin-sharp](https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/#tracedsvg) documentation for more information on `tracedSVG` and its configuration options._ | ||
| _Please see the | ||
| [gatsby-plugin-sharp](https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/#tracedsvg) | ||
| documentation for more information on `tracedSVG` and its configuration | ||
| options._ | ||
@@ -132,3 +168,4 @@ ## "Resolutions" queries | ||
| Pass in the data returned from the `resolutions` object in your query via the `resolutions` prop. e.g. `<Img resolutions={resolutions} />` | ||
| Pass in the data returned from the `resolutions` object in your query via the | ||
| `resolutions` prop. e.g. `<Img resolutions={resolutions} />` | ||
@@ -154,3 +191,4 @@ ### Query | ||
| Pass in the data returned from the `sizes` object in your query via the `sizes` prop. e.g. `<Img sizes={sizes} />` | ||
| Pass in the data returned from the `sizes` object in your query via the `sizes` | ||
| prop. e.g. `<Img sizes={sizes} />` | ||
@@ -176,18 +214,22 @@ ### Query | ||
| | Name | Type | Description | | ||
| | ------------------------- | --------------- | ---------------------------------------- | | ||
| | `resolutions` | `object` | Data returned from the `resolutions` query | | ||
| | `sizes` | `object` | Data returned from the `sizes` query | | ||
| | `fadeIn` | `bool` | Defaults to fading in the image on load | | ||
| | `title` | `string` | Passed to the `img` element | | ||
| | `alt` | `string` | Passed to the `img` element | | ||
| | `className` | `string\|object` | Passed to the wrapper div. Object is needed to support Glamor's css prop | | ||
| | `outerWrapperClassName` | `string\|object` | Passed to the outer wrapper div. Object is needed to support Glamor's css prop | | ||
| | `style` | `object` | Spread into the default styles in the wrapper div | | ||
| | `position` | `string` | Defaults to `relative`. Pass in `absolute` to make the component `absolute` positioned | | ||
| | `backgroundColor` | `string\|bool` | Set a colored background placeholder. If true, uses "lightgray" for the color. You can also pass in any valid color string. | | ||
| | `onLoad` | `func` | A callback that is called when the full-size image has loaded. | ||
| | Name | Type | Description | | ||
| | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | | ||
| | `resolutions` | `object` | Data returned from the `resolutions` query | | ||
| | `sizes` | `object` | Data returned from the `sizes` query | | ||
| | `fadeIn` | `bool` | Defaults to fading in the image on load | | ||
| | `title` | `string` | Passed to the `img` element | | ||
| | `alt` | `string` | Passed to the `img` element | | ||
| | `className` | `string\|object` | Passed to the wrapper div. Object is needed to support Glamor's css prop | | ||
| | `outerWrapperClassName` | `string\|object` | Passed to the outer wrapper div. Object is needed to support Glamor's css prop | | ||
| | `style` | `object` | Spread into the default styles in the wrapper div | | ||
| | `position` | `string` | Defaults to `relative`. Pass in `absolute` to make the component `absolute` positioned | | ||
| | `backgroundColor` | `string\|bool` | Set a colored background placeholder. If true, uses "lightgray" for the color. You can also pass in any valid color string. | | ||
| | `onLoad` | `func` | A callback that is called when the full-size image has loaded. | | ||
| ## Some other stuff to be aware of | ||
| * If you want to set `display: none;` on a component using a `resolutions` prop, you need to also pass in to the style prop `{ display: 'inherit' }`.* Images don't load until JavaScript is loaded. Gatsby's automatic code splitting generally makes this fine but if images seem slow coming in on a page, check how much JavaScript is being loaded there. | ||
| * If you want to set `display: none;` on a component using a `resolutions` prop, | ||
| you need to also pass in to the style prop `{ display: 'inherit' }`.\* Images | ||
| don't load until JavaScript is loaded. Gatsby's automatic code splitting | ||
| generally makes this fine but if images seem slow coming in on a page, check | ||
| how much JavaScript is being loaded there. |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by3.99%
22825
- Number of lines in readme file
- increased by22.83%
226
No dependency changes