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 index 90860290cc10c..36e86a0296ae5 100644 --- 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 index 1c02da7e1f43d..a75c623aaa272 100644 --- a/docs/docs/reference/built-in-components/gatsby-plugin-image.md +++ b/docs/docs/reference/built-in-components/gatsby-plugin-image.md @@ -240,6 +240,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 index 05fc9cb2defed..fe9c2270d3f5d 100644 --- 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 @@ -191,6 +192,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)**_