The modern image processing API using gatsbyImageData field provides the recommended approach for handling images in Gatsby applications. This API integrates with gatsby-plugin-image to deliver optimized, responsive images with automatic format selection and lazy loading capabilities.
Creates optimized image data for use with gatsby-plugin-image components, providing automatic format optimization, responsive sizing, and performance enhancements.
/**
* Generate optimized image data for gatsby-plugin-image
* Available as a GraphQL field on ImageSharp nodes
*/
gatsbyImageData(
/** The layout for the image (default: CONSTRAINED) */
layout?: ImageLayout,
/** Display width for FIXED layout, max width for CONSTRAINED layout */
width?: Int,
/** Display height for FIXED layout, max height for CONSTRAINED layout */
height?: Int,
/** Aspect ratio for cropping, overrides calculated ratio */
aspectRatio?: Float,
/** Placeholder type while image loads (default: DOMINANT_COLOR) */
placeholder?: ImagePlaceholder,
/** Image formats to generate (default: [AUTO, WEBP]) */
formats?: ImageFormat[],
/** Pixel densities to generate (default: [1, 2]) */
outputPixelDensities?: Float[],
/** Custom breakpoints for FULL_WIDTH layout */
breakpoints?: Int[],
/** Sizes attribute for responsive images */
sizes?: String,
/** Default quality for all formats */
quality?: Int,
/** JPG-specific options */
jpgOptions?: JPGOptions,
/** PNG-specific options */
pngOptions?: PNGOptions,
/** WebP-specific options */
webpOptions?: WebPOptions,
/** AVIF-specific options */
avifOptions?: AVIFOptions,
/** Image transformation options */
transformOptions?: TransformOptions,
/** Background color for letterboxing */
backgroundColor?: String
): GatsbyImageData;
interface GatsbyImageData {
layout: ImageLayout;
width: number;
height: number;
images: {
sources: ImageSource[];
fallback: ImageFallback;
};
placeholder?: {
fallback: string;
};
backgroundColor?: string;
}
interface ImageSource {
srcSet: string;
type: string;
sizes?: string;
}
interface ImageFallback {
src: string;
srcSet: string;
sizes?: string;
}Usage Examples:
# Constrained responsive image (recommended)
query {
file(relativePath: { eq: "hero.jpg" }) {
childImageSharp {
gatsbyImageData(
layout: CONSTRAINED
width: 800
placeholder: BLURRED
formats: [AUTO, WEBP, AVIF]
)
}
}
}
# Fixed size image
query {
file(relativePath: { eq: "avatar.jpg" }) {
childImageSharp {
gatsbyImageData(
layout: FIXED
width: 200
height: 200
placeholder: DOMINANT_COLOR
)
}
}
}
# Full width hero image
query {
file(relativePath: { eq: "banner.jpg" }) {
childImageSharp {
gatsbyImageData(
layout: FULL_WIDTH
height: 400
formats: [AUTO, WEBP]
breakpoints: [750, 1080, 1366, 1920]
)
}
}
}Fine-grained control over image format generation and optimization settings.
interface JPGOptions {
/** JPG quality (1-100) */
quality?: Int;
/** Enable progressive JPG (default: true) */
progressive?: Boolean;
}
interface PNGOptions {
/** PNG quality (1-100) */
quality?: Int;
/** PNG compression speed (1-10, default: 4) */
compressionSpeed?: Int;
}
interface WebPOptions {
/** WebP quality (1-100) */
quality?: Int;
}
interface AVIFOptions {
/** AVIF quality (1-100) */
quality?: Int;
/** Enable lossless compression */
lossless?: Boolean;
/** Encoding speed (1-10) */
speed?: Int;
}Image transformation settings for cropping, rotation, and visual effects.
interface TransformOptions {
/** Convert image to grayscale (default: false) */
grayscale?: Boolean;
/** Apply duotone color effect */
duotone?: DuotoneGradient;
/** Rotation angle in degrees (default: 0) */
rotate?: Int;
/** Trim transparent/similar-color pixels (default: false) */
trim?: Float;
/** Focus area for cropping (default: ATTENTION) */
cropFocus?: ImageCropFocus;
/** Resize behavior (default: COVER) */
fit?: ImageFit;
}
interface DuotoneGradient {
/** Highlight color (required) */
highlight: String;
/** Shadow color (required) */
shadow: String;
/** Effect opacity (0-100) */
opacity?: Int;
}Configuration for different placeholder types displayed during image loading.
interface BlurredOptions {
/** Width of the blurred placeholder (default: 20px) */
width?: Int;
/** Format for the placeholder image */
toFormat?: ImageFormat;
}Usage Examples:
# Custom quality and format options
query {
file(relativePath: { eq: "product.jpg" }) {
childImageSharp {
gatsbyImageData(
width: 600
quality: 90
jpgOptions: { progressive: true }
webpOptions: { quality: 85 }
formats: [JPG, WEBP]
)
}
}
}
# Grayscale with custom crop focus
query {
file(relativePath: { eq: "portrait.jpg" }) {
childImageSharp {
gatsbyImageData(
width: 300
height: 400
transformOptions: {
grayscale: true
cropFocus: NORTH
}
)
}
}
}
# Blurred placeholder with custom settings
query {
file(relativePath: { eq: "background.jpg" }) {
childImageSharp {
gatsbyImageData(
layout: FULL_WIDTH
placeholder: BLURRED
blurredOptions: {
width: 40
toFormat: JPG
}
)
}
}
}