From 4f84533aa8bcd9a2030fb99aad335a5b4bcc4c33 Mon Sep 17 00:00:00 2001 From: Kelvin DeCosta <38982451+kelvindecosta@users.noreply.github.com> Date: Thu, 6 May 2021 16:37:59 +0300 Subject: [PATCH] docs(gatsby-plugin-image): Add docs for customizing default options (#30344) Co-authored-by: Lennart Co-authored-by: gatsbybot --- .../using-gatsby-plugin-image.md | 34 ++++++++++++++++++ .../gatsby-plugin-image.md | 34 ++++++++++++++++++ packages/gatsby-plugin-image/README.md | 35 +++++++++++++++++++ 3 files changed, 103 insertions(+) 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 c2d03131eae76..b62af87ef7a20 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 4aa79cc476221..7946d0a8ef4a3 100644 --- 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 index c619abc810b23..3e71fa527869b 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 @@ -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)**_