diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md
index 8aa8ffb0ce5f0..af2e64eb4c94b 100644
--- a/docs/docs/gatsby-config.md
+++ b/docs/docs/gatsby-config.md
@@ -1,5 +1,5 @@
---
-title: Gatsby Config
+title: Gatsby Config API
---
Site configuration options for a Gatsby site are placed in a file at the root of the project folder called `gatsby-config.js`.
diff --git a/docs/docs/gatsby-image.md b/docs/docs/gatsby-image.md
new file mode 100644
index 0000000000000..4ce1350f8cb61
--- /dev/null
+++ b/docs/docs/gatsby-image.md
@@ -0,0 +1,392 @@
+---
+title: Gatsby Image API
+---
+
+Part of what makes Gatsby sites so fast is its recommended approach to handling images. `gatsby-image` is a React component designed to work seamlessly with Gatsby’s [native image processing](https://image-processing.gatsbyjs.org/) capabilities powered by GraphQL and [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/) to easily and completely optimize image loading for your sites.
+
+> _Note: gatsby-image is **not** a drop-in replacement for ``. It’s optimized for fixed width/height images and images that stretch the full-width of a container._
+
+Demo: [https://using-gatsby-image.gatsbyjs.org/](https://using-gatsby-image.gatsbyjs.org/)
+
+## In this doc
+
+- [Setting up Gatsby Image](#setting-up-gatsby-image)
+- [Types of images with gatsby-image](#types-of-images-with-gatsby-image)
+ - [Fixed images and parameters](#images-with-a-fixed-width-and-height)
+ - [Fluid images and parameters](#images-that-stretch-across-a-fluid-container)
+ - [Resized images](#resized-images)
+ - [Shared query parameters](#shared-query-parameters)
+- [Image query fragments](#image-query-fragments)
+- [Gatsby Image props](#gatsby-image-props)
+
+## Setting up Gatsby Image
+
+To start working with Gatsby Image, install the `gatsby-image` package along with necessary plugins `gatsby-transformer-sharp` and `gatsby-plugin-sharp`. Reference the packages in your `gatsby-config.js` file. You can also provide additional options to [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) in your config file.
+
+A common way to source images is to install and use `gatsby-source-filesystem` to connect your local files, but other source plugins can be used as well, such as `gatsby-source-contentful`, `gatsby-source-datocms` and `gatsby-source-sanity`.
+
+```bash
+npm install --save gatsby-image gatsby-plugin-sharp gatsby-transformer-sharp
+```
+
+```js:title=gatsby-config.js
+module.exports = {
+ plugins: [
+ `gatsby-transformer-sharp`,
+ `gatsby-plugin-sharp`,
+ {
+ resolve: `gatsby-source-filesystem`,
+ options: {
+ path: `${__dirname}/src/data/`,
+ },
+ },
+ ],
+}
+```
+
+_For in-depth install instructions, check out the docs on [Using Gatsby Image](/docs/using-gatsby-image/)._
+
+### Gatsby image starts with a query
+
+To feed file data in to Gatsby Image, set up a [GraphQL query](/docs/graphql-reference/) and either pass it into a component as props or write it directly in the component. One technique is to leverage the [`useStaticQuery`](/docs/use-static-query/) hook.
+
+Common GraphQL queries for sourcing images include `file` from [gatsby-source-filesystem](/packages/gatsby-source-filesystem/), and both `imageSharp` and `allImageSharp` from [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/), but ultimately the options available to you will depend on your content sources.
+
+> Note: you can also use [GraphQL aliases](/docs/graphql-reference/#aliasing) for querying multiple images of the same type.
+
+See below for code examples of queries and how to use them in components.
+
+## Types of images with `gatsby-image`
+
+Gatsby image objects are created through GraphQL methods. There are two types of image optimizations available, _fixed_ and _fluid_, which create multiple image sizes (1x, 1.5x, etc.). There is also the _resize_ method, which returns a single image.
+
+### Images with a _fixed_ width and height
+
+Automatically create images for different resolutions at a set width or height — Gatsby creates responsive images for 1x, 1.5x, and 2x pixel densities using the `` element.
+
+Once you've queried for a `fixed` image to retrieve its data, you can pass that data into the `Img` component:
+
+```jsx
+import { useStaticQuery } from "gatsby"
+import Img from "gatsby-image"
+
+export default () => {
+ const data = useStaticQuery(query`
+ file(relativePath: { eq: "images/default.jpg" }) {
+ childImageSharp {
+ # Specify a fixed image and fragment.
+ # The default width is 400 pixels
+ // highlight-start
+ fixed {
+ ...GatsbyImageSharpFixed
+ }
+ // highlight-end
+ }
+ }
+ `)
+ return (
+
+
Hello gatsby-image
+
+
+ )
+}
+```
+
+#### Fixed image query parameters
+
+In a query, you can specify options for fixed images.
+
+- `width` (int, default: 400)
+- `height` (int)
+- `quality` (int, default: 50)
+
+#### Returns
+
+- `base64` (string)
+- `aspectRatio` (float)
+- `width` (float)
+- `height` (float)
+- `src` (string)
+- `srcSet` (string)
+
+This is where fragments like `GatsbyImageSharpFixed` come in handy, as they'll return all the above items in one line without having to type them all out:
+
+```graphql
+file(relativePath: { eq: "images/default.jpg" }) {
+ childImageSharp {
+ // highlight-start
+ fixed(width: 400, height: 400) {
+ ...GatsbyImageSharpFixed
+ // highlight-end
+ }
+ }
+}
+```
+
+Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fixed) README.
+
+### Images that stretch across a _fluid_ container
+
+Create flexible sizes for an image that stretches to fill its container. E.g. for a container whose max width is 800px, the automatic sizes would be: 200px, 400px, 800px, 1200px and 1600px – enough to provide close to the optimal image size for every device size / screen resolution. If you want more control over which sizes are output you can use the `srcSetBreakpoints` parameter.
+
+Once you've queried for a `fluid` image to retrieve its data, you can pass that data into the `Img` component:
+
+```jsx
+import { useStaticQuery } from "gatsby"
+import Img from "gatsby-image"
+
+export default () => {
+ const data = useStaticQuery(query`
+ file(relativePath: { eq: "images/default.jpg" }) {
+ childImageSharp {
+ # Specify a fluid image and fragment
+ # The default maxWidth is 800 pixels
+ // highlight-start
+ fluid {
+ ...GatsbyImageSharpFluid
+ }
+ // highlight-end
+ }
+ }
+ `)
+ return (
+
+
Hello gatsby-image
+
+
+ )
+}
+```
+
+#### Fluid image query parameters
+
+In a query, you can specify options for fluid images.
+
+- `maxWidth` (int, default: 800)
+- `maxHeight`(int)
+- `quality` (int, default: 50)
+- `srcSetBreakpoints` (array of int, default: [])
+- `fit` (string, default: `[sharp.fit.cover][6]`)
+- `background` (string, default: `rgba(0,0,0,1)`)
+
+#### Returns
+
+- `base64` (string)
+- `src` (string)
+- `width` (int)
+- `height` (int)
+- `aspectRatio` (float)
+- `src` (string)
+- `srcSet` (string)
+
+This is where fragments like `GatsbyImageSharpFluid` come in handy, as they'll return all the above items in one line without having to type them all out:
+
+```graphql
+file(relativePath: { eq: "images/default.jpg" }) {
+ childImageSharp {
+ // highlight-start
+ fluid(maxWidth: 400) {
+ ...GatsbyImageSharpFluid
+ // highlight-end
+ }
+ }
+}
+```
+
+Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fluid) README.
+
+### Resized images
+
+In addition to _fixed_ and _fluid_ images, the gatsby-image API allows you to call a `resize` method with `gatsby-plugin-sharp` to return a single image as opposed to multiple sizes. There are no default fragments available for the resize method.
+
+#### Parameters
+
+- `width` (int, default: 400)
+- `height` (int)
+- `quality` (int, default: 50)
+- `jpegProgressive` (bool, default: true)
+- `pngCompressionLevel` (int, default: 9)
+- `base64`(bool, default: false)
+
+#### Returns
+
+Resize returns an object with the following items:
+
+- `src` (string)
+- `width` (int)
+- `height` (int)
+- `aspectRatio` (float)
+
+```graphql
+allImageSharp {
+ edges {
+ node {
+ resize(width: 150, height: 150, grayscale: true) {
+ src
+ }
+ }
+ }
+}
+```
+
+### Shared query parameters
+
+In addition to `gatsby-plugin-sharp` settings in `gatsby-config.js`, there are additional query options that apply to both _fluid_ and _fixed_ images:
+
+- `grayscale` (bool, default: false)
+- `duotone` (bool|obj, default: false)
+- `toFormat` (string, default: \`\`)
+- `cropFocus` (string, default: `[sharp.strategy.attention][6]`)
+- `pngCompressionSpeed` (int, default: 4)
+
+Here's an example of using the `duotone` option with a fixed image:
+
+```graphql
+fixed(
+ width: 800,
+ duotone: {
+ highlight: "#f00e2e",
+ shadow: "#192550"
+ }
+)
+```
+
+
+
+
+ Duotone | Before - After
+
+
+
+And an example of using the `grayscale` option with a fixed image:
+
+```graphql
+fixed(
+ grayscale: true
+)
+```
+
+
+
+
+ Grayscale | Before - After
+
+
+
+Read more in the [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp) README.
+
+## Image query fragments
+
+GraphQL includes a concept called "query fragments", which are a part of a query that can be reused. 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: using fragments in your queries depends on which data source(s) you have configured. Read more in the [gatsby-image](/packages/gatsby-image#fragments) README.
+
+### Common fragments with `gatsby-transformer-sharp`
+
+#### Fixed images
+
+- `GatsbyImageSharpFixed`
+- `GatsbyImageSharpFixed_noBase64`
+- `GatsbyImageSharpFixed_tracedSVG`
+- `GatsbyImageSharpFixed_withWebp`
+- `GatsbyImageSharpFixed_withWebp_noBase64`
+- `GatsbyImageSharpFixed_withWebp_tracedSVG`
+
+#### Fluid images
+
+- `GatsbyImageSharpFluid`
+- `GatsbyImageSharpFluid_noBase64`
+- `GatsbyImageSharpFluid_tracedSVG`
+- `GatsbyImageSharpFluid_withWebp`
+- `GatsbyImageSharpFluid_withWebp_noBase64`
+- `GatsbyImageSharpFluid_withWebp_tracedSVG`
+
+#### About `noBase64`
+
+If you don't want to use the [blur-up effect](https://using-gatsby-image.gatsbyjs.org/blur-up/), choose the fragment with `noBase64` at the end.
+
+#### About `tracedSVG`
+
+If you want to use the [traced placeholder SVGs](https://using-gatsby-image.gatsbyjs.org/traced-svg/), choose the fragment with `tracedSVG` at the end.
+
+#### About `withWebP`
+
+If you want to automatically use [WebP images](https://developers.google.com/speed/webp/) 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.
+
+Here's an example of using a non-default fragment from `gatsby-transformer-sharp`. Be sure to pick one that matches your desired image type (_fixed_ or _fluid_):
+
+```graphql
+file(relativePath: { eq: "images/default.jpg" }) {
+ childImageSharp {
+ fluid {
+ // highlight-next-line
+ ...GatsbyImageSharpFluid_tracedSVG
+ }
+ }
+}
+```
+
+For more info on how these options work, check out the Gatsby Image demo: [https://using-gatsby-image.gatsbyjs.org/](https://using-gatsby-image.gatsbyjs.org/)
+
+#### Additional plugin fragments
+
+Additionally, plugins supporting `gatsby-image` currently include [gatsby-source-contentful](/packages/gatsby-source-contentful/), [gatsby-source-datocms](https://github.com/datocms/gatsby-source-datocms) and [gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity). See the [gatsby-image](/packages/gatsby-image/#fragments) README for more details.
+
+## Gatsby-image props
+
+After you've made a query, you can pass additional options to the gatsby-image component.
+
+| Name | Type | Description |
+| ---------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `fixed` | `object` | Data returned from the `fixed` query |
+| `fluid` | `object` | Data returned from the `fluid` query |
+| `fadeIn` | `bool` | Defaults to fading in the image on load |
+| `durationFadeIn` | `number` | fade-in duration is set up to 500ms by default |
+| `title` | `string` | Passed to the rendered HTML `img` element |
+| `alt` | `string` | Passed to the rendered HTML `img` element. Defaults to an empty string, e.g. `alt=""` |
+| `crossOrigin` | `string` | Passed to the rendered HTML `img` element |
+| `className` | `string` / `object` | Passed to the wrapper element. Object is needed to support Glamor's css prop |
+| `style` | `object` | Spread into the default styles of the wrapper element |
+| `imgStyle` | `object` | Spread into the default styles of the actual `img` element |
+| `placeholderStyle` | `object` | Spread into the default styles of the placeholder `img` element |
+| `placeholderClassName` | `string` | A class that is passed to the placeholder `img` element |
+| `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. |
+| `onStartLoad` | `func` | A callback that is called when the full-size image starts loading, it gets the parameter `{ wasCached: }` provided. |
+| `onError` | `func` | A callback that is called when the image fails to load. |
+| `Tag` | `string` | Which HTML tag to use for wrapping elements. Defaults to `div`. |
+| `objectFit` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `cover`. |
+| `objectPosition` | `string` | Passed to the `object-fit-images` polyfill when importing from `gatsby-image/withIEPolyfill`. Defaults to `50% 50%`. |
+| `loading` | `string` | Set the browser's native lazy loading attribute. One of `lazy`, `eager` or `auto`. Defaults to `lazy`. |
+| `critical` | `bool` | Opt-out of lazy-loading behavior. Defaults to `false`. Deprecated, use `loading` instead. |
+
+Here are some usage examples:
+
+```jsx
+ {
+ // do loading stuff
+ }}
+ onStartLoad={({ wasCached }) => {
+ // do stuff on start of loading
+ // optionally with the wasCached boolean parameter
+ }}
+ onError={(error) => {
+ // do error stuff
+ }}
+ Tag="custom-image"
+ loading="eager"
+/>
+```
diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md
index 7d2ee5f581012..3d78e7bf047c2 100644
--- a/docs/docs/gatsby-link.md
+++ b/docs/docs/gatsby-link.md
@@ -1,5 +1,5 @@
---
-title: Gatsby Link
+title: Gatsby Link API
---
For internal navigation, Gatsby includes a built-in `` component as well as a `navigate` function which is used for programmatic navigation.
diff --git a/docs/docs/images-and-files.md b/docs/docs/images-and-files.md
index 8b8699e51d063..8e6fc012bd587 100644
--- a/docs/docs/images-and-files.md
+++ b/docs/docs/images-and-files.md
@@ -1,8 +1,9 @@
---
-title: Images, Files, and Video
-overview: true
+title: Images, Files, and Video in Gatsby
---
-Gatsby provides multiple solutions for adding images, video, and files into your projects. This section will walk you through several common patterns for handling media with Gatsby.
+Gatsby provides multiple solutions for adding images, video, and files to your projects. And a pro tip: you don't necessarily have to use GraphQL! From [imports](/docs/importing-assets-into-files/) and use of the [static folder](/docs/static-folder/) to dynamic queries with [Gatsby Image](/docs/using-gatsby-image/) to prevent image bloat, you've got options.
+
+This section will walk you through several common patterns for handling media with Gatsby, where you can learn about the pros and cons of each method.
diff --git a/docs/docs/images/dancing-otter.gif b/docs/docs/images/dancing-otter.gif
new file mode 100644
index 0000000000000..bb7e8e994a6e4
Binary files /dev/null and b/docs/docs/images/dancing-otter.gif differ
diff --git a/docs/docs/images/duotone-before-after.png b/docs/docs/images/duotone-before-after.png
new file mode 100644
index 0000000000000..0e00ec90b8ec0
Binary files /dev/null and b/docs/docs/images/duotone-before-after.png differ
diff --git a/docs/docs/images/grayscale-before-after.png b/docs/docs/images/grayscale-before-after.png
new file mode 100644
index 0000000000000..d817a0b415de7
Binary files /dev/null and b/docs/docs/images/grayscale-before-after.png differ
diff --git a/docs/docs/using-gatsby-image.md b/docs/docs/using-gatsby-image.md
index 23a0beff0451d..27ecba4502520 100644
--- a/docs/docs/using-gatsby-image.md
+++ b/docs/docs/using-gatsby-image.md
@@ -1,9 +1,7 @@
---
-title: Using Gatsby Image
+title: Using Gatsby Image to Prevent Image Bloat
---
-# Using gatsby-image to prevent image bloat
-
`gatsby-image` is a React component designed to work seamlessly with Gatsby’s GraphQL queries ([`gatsby-image` plugin README](/packages/gatsby-image/)). It combines [Gatsby’s native image processing](https://image-processing.gatsbyjs.org/) capabilities with advanced image loading techniques to easily and completely optimize image loading for your sites. `gatsby-image` uses [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/) to power its image transformations.
> _Warning: gatsby-image is **not** a drop-in replacement for ``. It’s optimized for fixed width/height images and images that stretch the full-width of a container. Some ways you can use `` won’t work with gatsby-image._
@@ -16,6 +14,8 @@ title: Using Gatsby Image
- holds an image’s position so your page doesn’t jump around as images load
- makes it easy to add a placeholder—either a gray background or a blurry version of the image.
+_For more complete API information, check out the [Gatsby Image API](/docs/gatsby-image/) docs._
+
## Problem
Large, unoptimized images dramatically slow down your site.
@@ -105,11 +105,12 @@ export default ({ data }) => (
This GraphQL query creates multiple sizes of the image and when the page is rendered the image that is appropriate for the current screen resolution (e.g. desktop, mobile, and everything in between) is used. The `gatsby-image` component automatically enables a blur-up effect as well as lazy loading images that are not currently on screen.
-So this is all very nice and it’s far better to be able to use this from NPM vs. implementing it yourself or cobbling together several standalone libraries.
+So this is all very nice and it’s far better to be able to use this from npm vs. implementing it yourself or cobbling together several standalone libraries.
-### References:
+### Additional resources
-- [Gatsby image plugin README file](/packages/gatsby-image/)
+- [Gatsby Image API docs](/docs/gatsby-image/)
+- [gatsby-image plugin README file](/packages/gatsby-image/)
- [Source code for an example site using gatsby-image](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-gatsby-image)
- [Blog articles about gatsby-image](/blog/tags/gatsby-image/)
- [Starters that use gatsby-image](/starters/?d=gatsby-image&v=2)
diff --git a/docs/docs/working-with-gifs.md b/docs/docs/working-with-gifs.md
new file mode 100644
index 0000000000000..bcbf9a3313b1b
--- /dev/null
+++ b/docs/docs/working-with-gifs.md
@@ -0,0 +1,42 @@
+---
+title: Working With GIFs
+---
+
+If you're building a blog with Gatsby, chances are you'll want to include some animated GIFs: who wouldn't want to include a dancing otter or cat GIF?
+
+## Including GIFs in components
+
+In Gatsby components and pages, you'll want to import animated GIFs instead of using Gatsby Image because of the way it optimizes image data for the responsive picture element.
+
+Here's an example:
+
+```jsx:title=pages/about.js
+import React from 'react'
+
+import Layout from '../components/layout'
+import otterGIF from '../gifs/otter.gif'
+
+const AboutPage = () => (
+ return (
+
+
+
+ )
+)
+
+export default AboutPage;
+```
+
+## Including GIFs in Markdown
+
+In Markdown posts and pages, including an animated GIF is the same as a static image:
+
+```markdown
+
+```
+
+
+
+Animated GIFs can be quite large in size, however, so be careful not to sabotage your webpages' performance with extremely large files. You could reduce file size by [optimizing the frames](https://skylilies.livejournal.com/244378.html) or converting them to video.
+
+> Note: beware that flashing and autoplaying GIFs can cause accessibility problems. One technique would be to add controls, such as using a package like [react-gif-player](https://www.npmjs.com/package/react-gif-player).
diff --git a/docs/docs/working-with-images.md b/docs/docs/working-with-images.md
index 8980cd0f0dff7..4516cb91ad578 100644
--- a/docs/docs/working-with-images.md
+++ b/docs/docs/working-with-images.md
@@ -90,3 +90,10 @@ export const query = graphql`
}
`
```
+
+### Additional resources
+
+- [Gatsby Image API docs](/docs/gatsby-image/)
+- [gatsby-image plugin README file](/packages/gatsby-image/)
+- [gatsby-plugin-sharp README file](/packages/gatsby-plugin-sharp/)
+- [gatsby-transformer-sharp README file](/packages/gatsby-transformer-sharp/)
diff --git a/packages/gatsby-image/README.md b/packages/gatsby-image/README.md
index d34a5d726ceb9..409fad98a03eb 100644
--- a/packages/gatsby-image/README.md
+++ b/packages/gatsby-image/README.md
@@ -10,7 +10,7 @@ optimize image loading for your sites. `gatsby-image` uses
[gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/)
to power its image transformations.
-_Warning: gatsby-image is **not** a drop-in replacement for ``. It's
+_Note: gatsby-image is **not** a drop-in replacement for ``. It's
optimized for fixed width/height images and images that stretch the full-width
of a container. Some ways you can use `` won't work with gatsby-image._
@@ -340,7 +340,7 @@ You will need to add it in your graphql query as is shown in the following snipp
| `fadeIn` | `bool` | Defaults to fading in the image on load |
| `durationFadeIn` | `number` | fading duration is set up to 500ms by default |
| `title` | `string` | Passed to the `img` element |
-| `alt` | `string` | Passed to the `img` element |
+| `alt` | `string` | Passed to the `img` element. Defaults to an empty string `alt=""` |
| `crossOrigin` | `string` | Passed to the `img` element |
| `className` | `string` / `object` | Passed to the wrapper element. Object is needed to support Glamor's css prop |
| `style` | `object` | Spread into the default styles of the wrapper element |
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
index c9c3f11f0d5f9..f16d54456d09e 100644
--- a/www/src/data/sidebars/doc-links.yaml
+++ b/www/src/data/sidebars/doc-links.yaml
@@ -88,6 +88,8 @@
link: /docs/working-with-video/
- title: Importing Media Content
link: /docs/importing-media-content/
+ - title: Working with GIFs
+ link: /docs/working-with-gifs/
- title: Sourcing Content and Data
link: /docs/content-and-data/
items:
@@ -347,6 +349,8 @@
items:
- title: Gatsby Link
link: /docs/gatsby-link/
+ - title: Gatsby Image
+ link: /docs/gatsby-image/
- title: Gatsby Config
link: /docs/gatsby-config/
- title: Gatsby Node APIs
+ 
+