docs(gatsby-plugin-image): Add docs for customizing default options (#…

…30344) Co-authored-by: Lennart <lekoarts@gmail.com> Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>
gatsbyjs · May 6, 2021 · 4f84533 · 4f84533
1 parent d0dee0d
commit 4f84533
Show file tree

Hide file tree

Showing 3 changed files with 103 additions and 0 deletions.
diff --git a/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md b/docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md
@@ -192,6 +192,40 @@ If you need to have dynamic images (such as if they are coming from a CMS), you
    `
    ```
 
+## Customizing the defaults
+
+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:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-sharp`,
+      options: {
+        defaults: {
+          formats: [`auto`, `webp`],
+          placeholder: `dominantColor`
+          quality: 50
+          breakpoints: [750, 1080, 1366, 1920]
+          backgroundColor: `transparent`
+          tracedSVGOptions: {}
+          blurredOptions: {}
+          jpgOptions: {}
+          pngOptions: {}
+          webpOptions: {}
+          avifOptions: {}
+        }
+      }
+    },
+    `gatsby-transformer-sharp`,
+    `gatsby-plugin-image`,
+  ],
+}
+```
+
 ## Using images from a CMS or CDN
 
 Many source plugins have native support for `gatsby-plugin-image`, with images served directly from a content delivery network (CDN). This means that builds are faster, because there is no need download images and process them locally. The query syntax varies according to the plugin, as do the supported transformation features and image formats. Make sure you update to the latest version of the source plugin to ensure there is support. For plugins that are not in this list you can use [dynamic images from `gatsby-transformer-sharp`](#dynamic-images).

diff --git a/docs/docs/reference/built-in-components/gatsby-plugin-image.md b/docs/docs/reference/built-in-components/gatsby-plugin-image.md
@@ -291,6 +291,40 @@ The Gatsby Image plugin uses [sharp](https://sharp.pixelplumbing.org) for image
 | `webpOptions`                           | None                                                                 | Options to pass to sharp when generating WebP images.                                                                                                                                                                                                                                                                                                                                                         |
 | `avifOptions`                           | None                                                                 | Options to pass to sharp when generating AVIF images.                                                                                                                                                                                                                                                                                                                                                         |
 
+## 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:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-sharp`,
+      options: {
+        defaults: {
+          formats: [`auto`, `webp`],
+          placeholder: `dominantColor`
+          quality: 50
+          breakpoints: [750, 1080, 1366, 1920]
+          backgroundColor: `transparent`
+          tracedSVGOptions: {}
+          blurredOptions: {}
+          jpgOptions: {}
+          pngOptions: {}
+          webpOptions: {}
+          avifOptions: {}
+        }
+      }
+    },
+    `gatsby-transformer-sharp`,
+    `gatsby-plugin-image`,
+  ],
+}
+```
+
 ## Helper functions
 
 There are a number of utility functions to help you work with `gatsbyImageData` objects. We strongly recommend that you do not try to access the internals of these objects directly, as the format could change.

diff --git a/packages/gatsby-plugin-image/README.md b/packages/gatsby-plugin-image/README.md
@@ -10,6 +10,7 @@ For full documentation on all configuration options, see [the Gatsby Image Plugi
 - [Using the Gatsby Image components](#using-the-gatsby-image-components)
   - [Static images](#static-images)
   - [Dynamic images](#dynamic-images)
+- [Customizing the default options](#customizing-the-default-options)
 - [Migrating to gatsby-plugin-image](#migrating)
 
 ## Installation
@@ -189,6 +190,40 @@ If you need to have dynamic images (such as if they are coming from a CMS), you
 
 For full APIs, see [Gatsby Image plugin reference guide](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image).
 
+## 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:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-sharp`,
+      options: {
+        defaults: {
+          formats: [`auto`, `webp`],
+          placeholder: `dominantColor`
+          quality: 50
+          breakpoints: [750, 1080, 1366, 1920]
+          backgroundColor: `transparent`
+          tracedSVGOptions: {}
+          blurredOptions: {}
+          jpgOptions: {}
+          pngOptions: {}
+          webpOptions: {}
+          avifOptions: {}
+        }
+      }
+    },
+    `gatsby-transformer-sharp`,
+    `gatsby-plugin-image`,
+  ],
+}
+```
+
 ## Migrating
 
 _Main article: **[Migrating from gatsby-image to gatsby-plugin-image](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide)**_