Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
gatsby-image
Advanced tools
Lazy-loading React image component with optional support for the blur-up effect.
The gatsby-image
package is now deprecated. The new Gatsby image plugin has better performance, cool new features and a simpler API. See the migration guide to learn how to upgrade.
Speedy, optimized images without the work.
gatsby-image
is a React component specially designed to work seamlessly with
Gatsby's GraphQL queries. It combines
Gatsby's native image processing
capabilities with advanced image loading techniques to easily and completely
optimize image loading for your sites. gatsby-image
uses
gatsby-plugin-sharp
to power its image transformations.
Note: gatsby-image is not a drop-in replacement for <img />
. It's
optimized for fixed width/height images and images that stretch the full-width
of a container. Some ways you can use <img />
won't work with gatsby-image.
Large, unoptimized images dramatically slow down your site.
But creating optimized images for websites has long been a thorny problem. Ideally you would:
Doing this consistently across a site feels like a task that can never be completed. 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.
This isn't ideal. Optimized images should be easy and the default.
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
and use it in place of the built-in img
.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.
npm install gatsby-image
Depending on the gatsby starter you used, you may need to include gatsby-transformer-sharp and gatsby-plugin-sharp as well, and make sure they are installed and included in your gatsby-config.
npm install gatsby-transformer-sharp gatsby-plugin-sharp
Then in your gatsby-config.js
:
plugins: [`gatsby-transformer-sharp`, `gatsby-plugin-sharp`]
Also, make sure you have set up a source plugin, so your images are available in graphql
queries. For example, if your images live in a project folder on the local filesystem, you would set up gatsby-source-filesystem
in gatsby-config.js
like so:
const path = require(`path`)
module.exports = {
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
name: `images`,
path: path.join(__dirname, `src`, `images`),
},
},
`gatsby-plugin-sharp`,
`gatsby-transformer-sharp`,
],
}
This is what a component using gatsby-image
looks like:
import React from "react"
import { graphql } from "gatsby"
import Img from "gatsby-image"
export default ({ data }) => (
<div>
<h1>Hello gatsby-image</h1>
<Img fixed={data.file.childImageSharp.fixed} />
</div>
)
export const query = graphql`
query {
file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) {
childImageSharp {
# Specify the image processing specifications right in the query.
# Makes it trivial to update as your page's design changes.
fixed(width: 125, height: 125) {
...GatsbyImageSharpFixed
}
}
}
}
`
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, this post by Hunter Chang (which also includes some details about changes to gatsby-image for Gatsby v2): An Intro To Gatsby Image V2, or this free playlist on egghead.io with examples for using gatsby-image
.
If you'd like to include a polyfill for the object-fit
/object-position
CSS properties (which aren't supported by default in Internet Explorer), import from gatsby-image/withIEPolyfill
instead:
// 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.
There are two types of responsive images supported by gatsby-image.
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.
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 fixed
— which you can see in the sample
component above. For the second type, you do a similar query but for a child
object called fluid
.
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, you can not currently use these fragments in the GraphiQL IDE.
Plugins supporting gatsby-image
currently include
gatsby-transformer-sharp,
gatsby-source-contentful, gatsby-source-datocms and gatsby-source-sanity.
Their fragments are:
GatsbyImageSharpFixed
GatsbyImageSharpFixed_noBase64
GatsbyImageSharpFixed_tracedSVG
GatsbyImageSharpFixed_withWebp
GatsbyImageSharpFixed_withWebp_noBase64
GatsbyImageSharpFixed_withWebp_tracedSVG
GatsbyImageSharpFluid
GatsbyImageSharpFluid_noBase64
GatsbyImageSharpFluid_tracedSVG
GatsbyImageSharpFluid_withWebp
GatsbyImageSharpFluid_withWebp_noBase64
GatsbyImageSharpFluid_withWebp_tracedSVG
GatsbyImageSharpFluidLimitPresentationSize
GatsbyContentfulFixed
GatsbyContentfulFixed_noBase64
GatsbyContentfulFixed_tracedSVG
GatsbyContentfulFixed_withWebp
GatsbyContentfulFixed_withWebp_noBase64
GatsbyContentfulFluid
GatsbyContentfulFluid_noBase64
GatsbyContentfulFluid_tracedSVG
GatsbyContentfulFluid_withWebp
GatsbyContentfulFluid_withWebp_noBase64
GatsbyDatoCmsFixed
GatsbyDatoCmsFixed_noBase64
GatsbyDatoCmsFixed_tracedSVG
GatsbyDatoCmsFluid
GatsbyDatoCmsFluid_noBase64
GatsbyDatoCmsFluid_tracedSVG
GatsbySanityImageFixed
GatsbySanityImageFixed_noBase64
GatsbySanityImageFluid
GatsbySanityImageFluid_noBase64
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.
For more information about these options, please see the Gatsby Image API.
Please see the
gatsby-plugin-sharp
documentation for more information on tracedSVG
and its configuration
options.
Pass in the data returned from the fixed
object in your query via the
fixed
prop. e.g. <Img fixed={fixed} />
{
imageSharp {
# Other options include height (set both width and height to crop),
# grayscale, duotone, rotate, etc.
fixed(width: 400) {
# Choose either the fragment including a small base64ed image, a traced placeholder SVG, or one without.
...GatsbyImageSharpFixed
}
}
}
Pass in the data returned from the fluid
object in your query via the fluid
prop. e.g. <Img fluid={fluid} />
{
imageSharp {
# i.e. the max width of your container is 700 pixels.
#
# Other options include maxHeight (set both maxWidth and maxHeight to crop),
# grayscale, duotone, rotate, etc.
fluid(maxWidth: 700) {
# Choose either the fragment including a small base64ed image, a traced placeholder SVG, or one without.
...GatsbyImageSharpFluid_noBase64
}
}
}
As mentioned previously, images using the fluid type are stretched to match the container's width and height. In the case where the image's width or height is smaller than the available viewport, the image will stretch to match the container, potentially leading to unwanted problems and worsened image quality.
To counter this edge case one could use the GatsbyImageSharpFluidLimitPresentationSize
fragment to ask for additional presentation size properties.
{
childImageSharp {
fluid(maxWidth: 500, quality: 100) {
...GatsbyImageSharpFluid
...GatsbyImageSharpFluidLimitPresentationSize
}
}
}
gatsby-image
supports showing different images at different breakpoints, which is known as 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.
import React from "react"
import { graphql } from "gatsby"
import Img from "gatsby-image"
export default ({ data }) => {
// Set up the array of image data and `media` keys.
// You can have as many entries as you'd like.
const sources = [
data.mobileImage.childImageSharp.fluid,
{
...data.desktopImage.childImageSharp.fluid,
media: `(min-width: 768px)`,
},
]
return (
<div>
<h1>Hello art-directed gatsby-image</h1>
<Img fluid={sources} />
</div>
)
}
export const query = graphql`
query {
mobileImage: file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) {
childImageSharp {
fluid(maxWidth: 1000, quality: 100) {
...GatsbyImageSharpFluid
}
}
}
desktopImage: file(
relativePath: { eq: "blog/avatars/kyle-mathews-desktop.jpeg" }
) {
childImageSharp {
fluid(maxWidth: 2000, quality: 100) {
...GatsbyImageSharpFluid
}
}
}
}
`
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.
gatsby-image
propsName | Type | Description |
---|---|---|
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. |
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. |
fadeIn | bool | Defaults to fading in the image on load |
durationFadeIn | number | fading duration is set up to 500ms by default |
title | string | Passed to the img element |
alt | string | Passed to the img element. Defaults to an empty string alt="" |
crossOrigin | string | Passed to the img element |
className | string / object | Passed to the wrapper element. Object is needed to support Glamor's css prop |
style | object | Spread into the default styles of the wrapper element |
imgStyle | object | Spread into the default styles of the actual img element |
placeholderStyle | object | Spread into the default styles of the placeholder img element |
placeholderClassName | string | A class that is passed to the placeholder img element |
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. |
onStartLoad | func | A callback that is called when the full-size image starts loading, it gets the parameter { wasCached: boolean } provided. |
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 . |
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% . |
loading | string | Set the browser's native lazy loading attribute. One of lazy , eager or auto . Defaults to lazy . |
critical | bool | Opt-out of lazy-loading behavior. Defaults to false . Deprecated, use loading instead. |
draggable | bool | Set the img tag draggable to either false , true |
itemProp | string | Add an itemprop schema.org structured data attribute on the image. |
gatsby-plugin-sharp supports many additional arguments for transforming your images like
quality
, sizeByPixelDensity
, pngCompressionLevel
, cropFocus
, grayscale
and many more. See its documentation for more.
display: none;
on a component using a fixed
prop,
you need to also pass in to the style prop { display: 'inherit' }
.critical
will start loading immediately as the DOM is
parsed, but unless fadeIn
is set to false
, the transition from placeholder
to final image will not occur until after the component is mounted.<picture>
tag. This newer standard allows for
media types to be chosen by the browser without using JavaScript. It also is
backward compatible to older browsers (IE 11, etc).gatsby-image
, it won't work. For now, the best workaround is
to import the gif directly.IntersectionObserver
which is not available
in IE. A polyfill is recommended.FAQs
Lazy-loading React image component with optional support for the blur-up effect.
The npm package gatsby-image receives a total of 26,952 weekly downloads. As such, gatsby-image popularity was classified as popular.
We found that gatsby-image demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 19 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.