![Introducing Dashboard Analytics](https://cdn.sanity.io/images/cgdhsj6q/production/af327c5bd94708db501516a75da6870aef894c64-2286x1522.png?w=400&fit=max&auto=format)
Product
Introducing Dashboard Analytics
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
gatsby-image
Advanced tools
Lazy-loading React image component with optional support for the blur-up effect.
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.
Warning: 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 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.
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 --save 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 --save gatsby-transformer-sharp
npm install --save gatsby-plugin-sharp
Then in your gatsby-config.js
:
plugins: [
`gatsby-transformer-sharp`,
`gatsby-plugin-sharp`
];
This is what a component using gatsby-image
looks like:
import React from "react";
import Img from "gatsby-image";
export default ({ data }) => (
<div>
<h1>Hello gatsby-image</h1>
<Img resolutions={data.file.childImageSharp.resolutions} />
</div>
);
export const query = graphql`
query GatsbyImageSampleQuery {
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.
resolutions(width: 125, height: 125) {
...GatsbyImageSharpResolutions
}
}
}
}
`;
For another explanation of how to get started with gatsby-image, see this blog post by community member Kyle Gill Image Optimization Made Easy with Gatsby.js
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 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
.
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 and gatsby-source-datocms.
Their fragments are:
GatsbyImageSharpResolutions
GatsbyImageSharpResolutions_noBase64
GatsbyImageSharpResolutions_tracedSVG
GatsbyImageSharpResolutions_withWebp
GatsbyImageSharpResolutions_withWebp_noBase64
GatsbyImageSharpResolutions_withWebp_tracedSVG
GatsbyImageSharpSizes
GatsbyImageSharpSizes_noBase64
GatsbyImageSharpSizes_tracedSVG
GatsbyImageSharpSizes_withWebp
GatsbyImageSharpSizes_withWebp_noBase64
GatsbyImageSharpSizes_withWebp_tracedSVG
GatsbyContentfulResolutions
GatsbyContentfulResolutions_noBase64
GatsbyContentfulSizes
GatsbyContentfulSizes_noBase64
GatsbyDatoCmsResolutions
GatsbyDatoCmsResolutions_noBase64
GatsbyDatoCmsSizes
GatsbyDatoCmsSizes_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.
Please see the
gatsby-plugin-sharp
documentation for more information on tracedSVG
and its configuration
options.
Pass in the data returned from the resolutions
object in your query via the
resolutions
prop. e.g. <Img resolutions={resolutions} />
{
imageSharp {
# Other options include height (set both width and height to crop),
# grayscale, duotone, rotate, etc.
resolutions(width: 400) {
# Choose either the fragment including a small base64ed image, a traced placeholder SVG, or one without.
...GatsbyImageSharpResolutions
}
}
}
Pass in the data returned from the sizes
object in your query via the sizes
prop. e.g. <Img sizes={sizes} />
{
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.
sizes(maxWidth: 700) {
# Choose either the fragment including a small base64ed image, a traced placeholder SVG, or one without.
...GatsbyImageSharpSizes_noBase64
}
}
}
gatsby-image
propsName | 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. |
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.FAQs
Lazy-loading React image component with optional support for the blur-up effect.
The npm package gatsby-image receives a total of 8,681 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.
Product
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
Security News
A new OpenSSF report uncovers critical gaps in secure software training, with 75% of new developers unfamiliar with secure practices, highlighting urgent educational needs.
Security News
The 2023 Python Developers Survey reveals key trends in packaging, web frameworks, and developer demographics, highlighting a shift toward innovative tools as the Python community diversifies and grows among less experienced developers.