Image Processing with gatsby-transformer-sharp

gatsby-transformer-sharp exposes several image processing GraphQL functions built on the Sharp image processing library. With it and Gatsby Image you can easily add fast, optimized, responsive images to your site.

Consult the documentation or peep the code of this example site for more information.


Easily resize and intelligently crop images given a width and optionally a height.

The rotate option exposes Sharp's rotate .

resize(width: 125, height: 125, rotate: 180)

We also expose all of Sharp's crop options with cropFocus.

The default isATTENTION, which the Sharp documentation describes as "focus on the region with the highest luminance frequency, colour saturation and presence of skin tones" – which is why we actually see Mr. Gatsby toasting to us in the first thumbnail:

  • File undefined with a default crop
  • File undefined cropped to the bottom left

    cropFocus: SOUTHWEST

  • File undefined with an "entropy" crop

    cropFocus: ENTROPY

  • File undefined cropped to the centre

    cropFocus: CENTER


For when you want an image that stretches across a fluid width container but will download the smallest image needed for the device e.g. a smartphone will download a much smaller image than a desktop device.

If the max width of the container for the rendered markdown file is 800px, the fluid sizes would then be: 200, 400, 800, 1200, 1600, 2400 – enough to provide close to the optimal image size for every device size / screen resolution.

On top of that, fluid returns everything else (namely aspectRatio and a base64 image to use as a placeholder) you need to implement the "blur up"technique popularized by Medium and Facebook (and also available as a Gatsby plugin for Markdown content as gatsby-remark-images).

The duotone option (see I, II, III), given two hex colors shadow and highlight defining start and end color of the duotone gradient, converts the source image colors to match a gradient color chosen based on each pixels relative luminance.

The toFormat option lets you convert the source image to another image format. We use "PNG" here to ensure that the duotoned image does not show any JPG artifacts.

fluid(duotone: { highlight: "#f00e2e", shadow: "#192550" }, toFormat: PNG)

fluid(duotone: { highlight: "#0ec4f1", shadow: "#192550", opacity: 50 })

By setting an optional third parameter opacity for duotone, a semi-transparent version of the duotone'd image will be composited over the original allowing the original image and its colors to partially "shine through".


For when you want a fixed sized image but that has different sized thumbnails for screens that support different density of images

Automatically create images for different resolutions — we do 1x, 1.5x, and 2x.

The grayscale option uses Sharp's greyscale to convert the source image to 8-bit greyscale, 256 shades of grey.