npmpackage.info

Gathering detailed insights and metrics for gatsby-plugin-image

Other packages similar to gatsby-plugin-image

gatsby-plugin-sharp

5.14.0

Wrapper of the Sharp image manipulation library for Gatsby plugins

gatsby-transformer-sharp

5.14.0

Gatsby transformer plugin for images using Sharp

gatsby-remark-images

7.14.0

Processes images in markdown so they can be used in the production build.

gatsby-plugin-remote-images

3.6.6

Gatsby plugin to use gatsby-image on remote images from absolute path string fields on other nodes.

Gathering detailed insights and metrics for gatsby-plugin-image

gatsby-plugin-image - 3.14.0 | npmpackage.info

gatsby-plugin-image

The best React-based framework with performance, scalability and security built in.

3.14.0

55,905

MIT

JavaScript

631.85 kB

6.7

Installations

npm install gatsby-plugin-image

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS, UMD

Node Version

20.11.1

NPM Version

lerna/3.22.1/node@v20.11.1+arm64 (darwin)

Pull Requests

Open

213

Total

22,353

Closed

3,970

Merged

18,170

Issues

Open

216

Total

14,114

Closed

13,898

Releases

149

gatsby-source-shopify@9.0.0

Updated on Jan 07, 2025

gatsby-link@5.14.1

Updated on Jan 07, 2025

gatsby-source-contentful@8.15.0

Updated on Jan 07, 2025

v5.14.0

gatsby@5.14.0

Updated on Nov 06, 2024

gatsby-source-shopify@8.13.2

Updated on Oct 28, 2024

gatsby-source-wordpress@7.13.5 and 6 more...

gatsby-source-wordpress@7.13.5

Updated on Oct 28, 2024

View All 149 releases

Languages

JavaScript

TypeScript

CSS

HTML

MDX

Shell

Dockerfile

PHP

EJS

Python

Less

SCSS

Stylus

JavaScript (58.91%)

TypeScript (38.71%)

CSS (1.05%)

HTML (0.69%)

MDX (0.45%)

Shell (0.13%)

Dockerfile (0.03%)

PHP (0.02%)

EJS (0.01%)

Developer

gatsbyjs

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

MIT License

55,905 Stars

21,738 Commits

10,289 Forks

719 Watchers

316 Branches

3,966 Contributors

Updated on Jul 14, 2025

Maintainers

View All 3,966 Contributors

Package Meta Information

Latest Version

3.14.0

Package Id

gatsby-plugin-image@3.14.0

Unpacked Size

631.85 kB

Size

162.22 kB

File Count

NPM Version

lerna/3.22.1/node@v20.11.1+arm64 (darwin)

Node Version

20.11.1

Published on

Nov 06, 2024

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

gatsby-plugin-image

Adding responsive images to your site while maintaining high performance scores can be difficult to do manually. The Gatsby Image plugin handles the hard parts of producing images in multiple sizes and formats for you!

For full documentation on all configuration options, see the Gatsby Image Plugin reference guide

Installation
Using the Gatsby Image components
- Static images
- Dynamic images
Customizing the default options
Migrating to gatsby-plugin-image

Installation

Install gatsby-plugin-image and gatsby-plugin-sharp. Additionally install gatsby-source-filesystem if you are using static images, and gatsby-transformer-sharp if you are using dynamic images.

1npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-source-filesystem gatsby-transformer-sharp

Add the plugins to your gatsby-config.js:

1module.exports = {
2  plugins: [
3    `gatsby-plugin-image`,
4    `gatsby-plugin-sharp`,
5    `gatsby-transformer-sharp`, // Needed for dynamic images
6  ],
7}

Using the Gatsby Image components

Deciding which component to use

The Gatsby Image plugin includes two image components: one for static and one for dynamic images. An effective way to decide which you need is to ask yourself: "will this image be the same every time the component or template is used?". If it will always be the same, then use StaticImage. If it will change, whether through data coming from a CMS or different values passed to a component each time you use it, then it is a dynamic image and you should use the GatsbyImage component.

Static images

If you are using an image that will be the same each time the component is used, such as a logo or front page hero image, you can use the StaticImage component. The image can be a local file in your project or an image hosted on a remote server. Any remote images are downloaded and resized at build time.

Add the image to your project.

If you are using a local image, copy it into the project. A folder such as src/images is a good choice.
Add the StaticImage component to your template.

Import the component, then set the src prop to point to the image you added earlier. The path is relative to the source file itself. If your component file was src/components/dino.js, then you would load the image like this:
```
1import { StaticImage } from "gatsby-plugin-image"
2
3export function Dino() {
4  return <StaticImage src="../images/dino.png" alt="A dinosaur" />
5}
```
If you are using a remote image, pass the image URL in the src prop:
```
1import { StaticImage } from "gatsby-plugin-image"
2
3export function Kitten() {
4  return <StaticImage src="https://placekitten.com/800/600" alt="A kitten" />
5}
```
When you build your site, the StaticImage component will load the image from your filesystem or from the remote URL, and it will generate all the sizes and formats that you need to support a responsive image.

Because the image is loaded at build time, you cannot pass the filename in as a prop, or otherwise generate it outside of the component. It should either be a static string, or a local variable in the component's scope.

Important: Remote images are downloaded and resized at build time. If the image is changed on the other server, it will not be updated on your site until you rebuild.
Configure the image.

You configure the image by passing props to the <StaticImage /> component. You can change the size and layout, as well as settings such as the type of placeholder used when lazy loading. There are also advanced image processing options available. You can find the full list of options in the API docs.
```
1import { StaticImage } from "gatsby-plugin-image"
2
3export function Dino() {
4  return (
5    <StaticImage
6      src="../images/dino.png"
7      alt="A dinosaur"
8      placeholder="blurred"
9      layout="fixed"
10      width={200}
11      height={200}
12    />
13  )
14}
```
This component renders a 200px by 200px image of a dinosaur. Before loading it will have a blurred, low-resolution placeholder. It uses the "fixed" layout, which means the image does not resize with its container.

Restrictions on using `StaticImage`

There are a few technical restrictions to the way you can pass props into StaticImage. Most importantly, you can't use any of the parent component's props. For more information, refer to the Gatsby Image plugin reference guide. If you find yourself wishing you could use a prop passed from a parent for the image src then it's likely that you should be using a dynamic image.

Dynamic images

If you need to have dynamic images (such as if they are coming from a CMS), you can load them via GraphQL and display them using the GatsbyImage component.

Add the image to your page query.

Any GraphQL File object that includes an image will have a childImageSharp field that you can use to query the image data. The exact data structure will vary according to your data source, but the syntax is like this:
```
1query {
2  blogPost(id: { eq: $Id }) {
3    title
4    body
5    avatar {
6      childImageSharp {
7        gatsbyImageData(width: 200)
8      }
9    }
10  }
11}
```
Configure your image.

For all the configuration options, see the Gatsby Image plugin reference guide.

You configure the image by passing arguments to the gatsbyImageData resolver. You can change the size and layout, as well as settings such as the type of placeholder used when lazy loading. There are also advanced image processing options available. You can find the full list of options in the API docs.
```
1query {
2  blogPost(id: { eq: $Id }) {
3    title
4    body
5    author
6    avatar {
7      childImageSharp {
8        gatsbyImageData(
9          width: 200
10          placeholder: BLURRED
11          formats: [AUTO, WEBP, AVIF]
12        )
13      }
14    }
15  }
16}
```

Display the image.

You can then use the GatsbyImage component to display the image on the page. The getImage() function is an optional helper to make your code easier to read. It takes a File and returns file.childImageSharp.gatsbyImageData, which can be passed to the GatsbyImage component.

1import { graphql } from "gatsby"
2import { GatsbyImage, getImage } from "gatsby-plugin-image"
3
4function BlogPost({ data }) {
5  const image = getImage(data.blogPost.avatar)
6  return (
7    <section>
8      <h2>{data.blogPost.title}</h2>
9      <GatsbyImage image={image} alt={data.blogPost.author} />
10      <p>{data.blogPost.body}</p>
11    </section>
12  )
13}
14
15export const pageQuery = graphql`
16  query {
17    blogPost(id: { eq: $Id }) {
18      title
19      body
20      author
21      avatar {
22        childImageSharp {
23          gatsbyImageData(
24            width: 200
25            placeholder: BLURRED
26            formats: [AUTO, WEBP, AVIF]
27          )
28        }
29      }
30    }
31  }
32`

For full APIs, see Gatsby Image plugin reference guide.

Customizing the default options

You might find yourself using the same options (like placeholder, formats etc.) with most of your GatsbyImage and StaticImage instances. You can customize the default options with gatsby-plugin-sharp.

The following configuration describes the options that can be customized along with their default values:

1module.exports = {
2  plugins: [
3    {
4      resolve: `gatsby-plugin-sharp`,
5      options: {
6        defaults: {
7          formats: [`auto`, `webp`],
8          placeholder: `dominantColor`,
9          quality: 50,
10          breakpoints: [750, 1080, 1366, 1920],
11          backgroundColor: `transparent`,
12          tracedSVGOptions: {},
13          blurredOptions: {},
14          jpgOptions: {},
15          pngOptions: {},
16          webpOptions: {},
17          avifOptions: {},
18        }
19      }
20    },
21    `gatsby-transformer-sharp`,
22    `gatsby-plugin-image`,
23  ],
24}

Migrating

Main article: Migrating from gatsby-image to gatsby-plugin-image

If your site uses the old gatsby-image component, you can use a codemod to help you migrate to the new Gatsby Image components. This can update the code for most sites. To use the codemod, run this command in the root of your site:

1npx gatsby-codemods gatsby-plugin-image

This will convert all GraphQL queries and components to use the new plugin. For more details, see the migration guide.

No vulnerabilities found.

10

Security-Policy

Determines if the project has published a security policy.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

10

License

Determines if the project has defined a license.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

8

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

8

Maintained

Determines if the project is "actively maintained".

8

SAST

Determines if the project uses static code analysis.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 0

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/schedule-stale.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/gatsbyjs/gatsby/schedule-stale.yml/master?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/schedule-stale.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/gatsbyjs/gatsby/schedule-stale.yml/master?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/schedule-stale.yml:51: update your workflow using https://app.stepsecurity.io/secureworkflow/gatsbyjs/gatsby/schedule-stale.yml/master?enable=pin
Warn: containerImage not pinned by hash: .github/actions/gatsby-site-showcase-validator/Dockerfile:1: pin your Docker image by updating node:10-slim to node:10-slim@sha256:88932859e3d022d79161b99628c4c2c50e836437455e2d1b1a008d98367b10d6
Warn: containerImage not pinned by hash: .github/actions/high-priority-prs/Dockerfile:1: pin your Docker image by updating node:10-slim to node:10-slim@sha256:88932859e3d022d79161b99628c4c2c50e836437455e2d1b1a008d98367b10d6
Warn: containerImage not pinned by hash: .gitpod.Dockerfile:1: pin your Docker image by updating gitpod/workspace-full to gitpod/workspace-full@sha256:b1195dfae7ee9a12a89d195247c3e1357cc6a18360a41473dbec67525ef434e2
Warn: containerImage not pinned by hash: benchmarks/docker-runner/Dockerfile:1: pin your Docker image by updating node:14-buster to node:14-buster@sha256:a158d3b9b4e3fa813fa6c8c590b8f0a860e015ad4e59bbce5744d2f6fd8461aa
Warn: containerImage not pinned by hash: integration-tests/gatsby-source-wordpress/docker/wordpress/Dockerfile:1: pin your Docker image by updating wordpress:6.1 to wordpress:6.1@sha256:6991d7aea34c9746ab76ab22bcccdedc3594d37a148e08161c29b128bd50294c
Warn: containerImage not pinned by hash: integration-tests/gatsby-source-wordpress/docker/wp-cli/Dockerfile:1: pin your Docker image by updating wordpress:cli-php7.4 to wordpress:cli-php7.4@sha256:946a8b7f237f6cf90d8f04aff952544a0332d43374d598925dcf0180e4441c6c
Warn: npmCommand not pinned by hash: .gitpod.Dockerfile:8
Warn: npmCommand not pinned by hash: benchmarks/docker-runner/Dockerfile:6
Warn: npmCommand not pinned by hash: examples/build-all-examples.sh:34
Warn: npmCommand not pinned by hash: scripts/e2e-test.sh:17
Warn: npmCommand not pinned by hash: scripts/e2e-test.sh:17
Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 1 third-party GitHubAction dependencies pinned
Info: 0 out of 6 containerImage dependencies pinned
Info: 1 out of 6 npmCommand dependencies pinned

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

100 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6
Warn: Project is vulnerable to: GHSA-xq7p-g2vc-g82p
Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h
Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
Warn: Project is vulnerable to: GHSA-9pv7-vfvm-6vr7
Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-7hpj-7hhx-2fgx
Warn: Project is vulnerable to: GHSA-44fp-w29j-9vj5
Warn: Project is vulnerable to: GHSA-4pg4-qvpc-4q3h
Warn: Project is vulnerable to: GHSA-g5hg-p3ph-g8qg
Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
Warn: Project is vulnerable to: GHSA-x7hr-w5r2-h6wg
Warn: Project is vulnerable to: GHSA-rm97-x556-q36h
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5
Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
Warn: Project is vulnerable to: GHSA-pq67-2wwv-3xjx
Warn: Project is vulnerable to: GHSA-8cj5-5rvv-wf4v
Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986
Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Warn: Project is vulnerable to: GHSA-f9xv-q969-pqx4
Warn: Project is vulnerable to: GHSA-c429-5p7v-vgjp
Warn: Project is vulnerable to: GHSA-h5c3-5r3r-rr8q
Warn: Project is vulnerable to: GHSA-rmvr-2pp2-xj38
Warn: Project is vulnerable to: GHSA-xx4v-prfh-6cgc
Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9
Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
Warn: Project is vulnerable to: GHSA-wg6g-ppvx-927h
Warn: Project is vulnerable to: GHSA-7gc6-qh9x-w6h8
Warn: Project is vulnerable to: GHSA-8gh8-hqwg-xf34
Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97
Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj
Warn: Project is vulnerable to: GHSA-pfq8-rq6v-vf5m
Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
Warn: Project is vulnerable to: GHSA-2pr6-76vf-7546
Warn: Project is vulnerable to: GHSA-8j8c-7jfh-h6hx
Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
Warn: Project is vulnerable to: GHSA-8cf7-32gw-wr33
Warn: Project is vulnerable to: GHSA-hjrf-2m68-5959
Warn: Project is vulnerable to: GHSA-qwph-4952-7xr6
Warn: Project is vulnerable to: GHSA-3wc5-fcw2-2329
Warn: Project is vulnerable to: GHSA-64fm-8hw2-v72w
Warn: Project is vulnerable to: GHSA-f98w-7cxr-ff2h
Warn: Project is vulnerable to: GHSA-cg87-wmx4-v546
Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
Warn: Project is vulnerable to: GHSA-w7rc-rwvf-8q5r
Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
Warn: Project is vulnerable to: GHSA-px4h-xg32-q955
Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
Warn: Project is vulnerable to: GHSA-8g77-54rh-46hx
Warn: Project is vulnerable to: GHSA-3j8f-xvm3-ffx4
Warn: Project is vulnerable to: GHSA-4p35-cfcx-8653
Warn: Project is vulnerable to: GHSA-7f3x-x4pr-wqhj
Warn: Project is vulnerable to: GHSA-jpp7-7chh-cf67
Warn: Project is vulnerable to: GHSA-q6wq-5p59-983w
Warn: Project is vulnerable to: GHSA-j9fq-vwqv-2fm2
Warn: Project is vulnerable to: GHSA-pqw5-jmp5-px4v
Warn: Project is vulnerable to: GHSA-566m-qj78-rww5
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-rxrc-rgv4-jpvx
Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
Warn: Project is vulnerable to: GHSA-vx3p-948g-6vhq
Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
Warn: Project is vulnerable to: GHSA-w5p7-h5w8-2hfq
Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v
Warn: Project is vulnerable to: GHSA-38fc-wpqx-33j7
Warn: Project is vulnerable to: GHSA-fhg7-m89q-25r3
Warn: Project is vulnerable to: GHSA-g3ch-rx76-35fx
Warn: Project is vulnerable to: GHSA-g78m-2chm-r7qv
Warn: Project is vulnerable to: GHSA-4r6h-8v6p-xvw6
Warn: Project is vulnerable to: GHSA-5pgg-2g8v-p4x9
Warn: Project is vulnerable to: GHSA-h6q6-9hqw-rwfv
Warn: Project is vulnerable to: GHSA-5fg8-2547-mr8q
Warn: Project is vulnerable to: GHSA-crh6-fp67-6883
Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh

Score

6.7

/10

Last Scanned on 2025-07-07

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

Other packages similar to gatsby-plugin-image

Other packages similar to gatsby-plugin-image

gatsby-plugin-image

Installations

Developer Guide

Yes

CommonJS, UMD

20.11.1

lerna/3.22.1/node@v20.11.1+arm64 (darwin)

Pull Requests

213

22,353

3,970

18,170

Issues

216

14,114

13,898

Releases

Languages

Developer

Download Statistics

GitHub Statistics

Maintainers

Package Meta Information

Total Downloads

NaN

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Peer Dependencies

Dev Dependencies

gatsby-plugin-image

Contents

Installation

Using the Gatsby Image components

Deciding which component to use

Static images

Restrictions on using StaticImage

Dynamic images

Customizing the default options

Migrating

10

10

10

10

10

8

8

8

0

0

0

0

6.7

/10

Restrictions on using `StaticImage`