Image Components

/**
 * Display optimized images sourced from GraphQL with progressive loading
 * @param props - Component props including image data and display options
 * @returns JSX element with optimized image rendering
 */
function GatsbyImage(props: GatsbyImageProps): JSX.Element;

interface GatsbyImageProps {
  /** Alt text for the image (required for accessibility) */
  alt: string;
  /** Image data from GraphQL query (required) */
  image: IGatsbyImageData;
  /** HTML element to render as wrapper (default: 'div') */
  as?: ElementType;
  /** CSS class for the wrapper element */
  className?: string;
  /** CSS class for the img element */
  imgClassName?: string;
  /** Inline styles for the img element */
  imgStyle?: CSSProperties;
  /** Background color shown during loading */
  backgroundColor?: string;
  /** CSS object-fit property for the image */
  objectFit?: CSSProperties["objectFit"];
  /** CSS object-position property for the image */
  objectPosition?: CSSProperties["objectPosition"];
  /** Callback when image finishes loading */
  onLoad?: (event: { wasCached: boolean }) => void;
  /** Callback when image fails to load */
  onError?: ReactEventHandler<HTMLImageElement>;
  /** Callback when image starts loading */
  onStartLoad?: (event: { wasCached: boolean }) => void;
}

import React from "react";
import { graphql, useStaticQuery } from "gatsby";
import { GatsbyImage, getImage } from "gatsby-plugin-image";

// Basic usage with GraphQL
const BasicExample = () => {
  const data = useStaticQuery(graphql`
    query {
      file(relativePath: { eq: "hero.jpg" }) {
        childImageSharp {
          gatsbyImageData(width: 800, placeholder: BLURRED)
        }
      }
    }
  `);

  const image = getImage(data.file);

  return (
    <GatsbyImage
      image={image}
      alt="Hero image"
    />
  );
};

// Advanced usage with styling and callbacks
const AdvancedExample = ({ imageData }) => (
  <GatsbyImage
    image={imageData}
    alt="Product image"
    className="product-image-wrapper"
    imgClassName="product-image"
    backgroundColor="#f0f0f0"
    objectFit="cover"
    objectPosition="center"
    onLoad={({ wasCached }) => {
      console.log(`Image loaded ${wasCached ? 'from cache' : 'from network'}`);
    }}
    onError={() => console.error('Image failed to load')}
  />
);

/**
 * Display static images processed at build time with Babel transformation
 * @param props - Component props including source path and processing options
 * @returns JSX element with optimized static image
 */
function StaticImage(props: IStaticImageProps): JSX.Element;

interface IStaticImageProps extends Omit<GatsbyImageProps, "image"> {
  /** Source URL or path to image file (required) */
  src: string;
  /** Optional filename for processing */
  filename?: string;
  /** Desired width in pixels */
  width?: number;
  /** Desired height in pixels */
  height?: number;
  /** Aspect ratio as width/height */
  aspectRatio?: number;
  /** Image layout strategy */
  layout?: Layout;
  /** Type of placeholder to show during loading */
  placeholder?: "tracedSVG" | "dominantColor" | "blurred" | "none";
  /** Traced SVG options */
  tracedSVGOptions?: Record<string, unknown>;
  /** Output image formats to generate */
  formats?: Array<ImageFormat>;
  /** Image quality from 1-100 */
  quality?: number;
  /** Responsive sizes attribute for the image */
  sizes?: string;
  /** Sharp transformation options */
  transformOptions?: {
    fit?: Fit;
    cropFocus?: number | string;
    duotone?: {
      highlight: string;
      shadow: string;
      opacity?: number;
    };
    grayscale?: boolean;
    rotate?: number;
    trim?: number;
  };
  /** JPEG-specific options */
  jpgOptions?: Record<string, unknown>;
  /** PNG-specific options */
  pngOptions?: Record<string, unknown>;
  /** WebP-specific options */
  webpOptions?: Record<string, unknown>;
  /** AVIF-specific options */
  avifOptions?: Record<string, unknown>;
  /** Blurred placeholder options */
  blurredOptions?: { width?: number; toFormat?: ImageFormat };
  /** Custom breakpoints for responsive images */
  breakpoints?: Array<number>;
  /** Output pixel densities */
  outputPixelDensities?: Array<number>;
}

type Layout = "fixed" | "constrained" | "fullWidth";
type ImageFormat = "jpg" | "png" | "webp" | "avif" | "auto" | "";
type Fit = "cover" | "fill" | "inside" | "outside" | "contain";

import React from "react";
import { StaticImage } from "gatsby-plugin-image";

// Basic static image
const BasicStatic = () => (
  <StaticImage
    src="../images/hero.jpg"
    alt="Hero image"
    width={800}
    height={600}
  />
);

// Advanced static image with processing options
const AdvancedStatic = () => (
  <StaticImage
    src="../images/product.jpg"
    alt="Product showcase"
    layout="constrained"
    width={1200}
    height={800}
    placeholder="blurred"
    formats={["webp", "avif", "jpg"]}
    quality={90}
    transformOptions={{
      fit: "cover",
      cropFocus: "center",
    }}
    webpOptions={{ quality: 85 }}
    avifOptions={{ quality: 80, speed: 2 }}
  />
);

// Full-width responsive image
const ResponsiveStatic = () => (
  <StaticImage
    src="../images/banner.jpg"
    alt="Page banner"
    layout="fullWidth"
    aspectRatio={16 / 9}
    placeholder="dominantColor"
    sizes="100vw"
  />
);

/**
 * Render main image with noscript fallback for accessibility
 * @param props - Picture component props
 * @returns JSX element with main image and fallback
 */
function MainImage(props: PictureProps): JSX.Element;

interface PictureProps {
  /** Array of responsive image sources */
  sources: Array<{
    srcSet: string;
    type: string;
    sizes?: string;
  }>;
  /** Fallback image data */
  fallback: {
    src: string;
    srcSet: string;
    sizes?: string;
  };
  /** Image alt text */
  alt: string;
  /** CSS class for the img element */
  className?: string;
  /** Inline styles for the img element */
  style?: CSSProperties;
  /** Loading strategy */
  loading?: "lazy" | "eager";
  /** Decoding hint */
  decoding?: "async" | "sync" | "auto";
}

/**
 * Render placeholder content during image loading
 * @param props - Placeholder configuration
 * @returns JSX element with placeholder content
 */
function Placeholder(props: PlaceholderProps): JSX.Element;

interface PlaceholderProps {
  /** Placeholder image URL */
  fallback?: string;
  /** Responsive sources for placeholder */
  sources?: Array<{
    srcSet: string;
    type: string;
    sizes?: string;
  }>;
  /** CSS class for placeholder element */
  className?: string;
  /** Inline styles for placeholder */
  style?: CSSProperties;
}

import React from "react";
import { Placeholder } from "gatsby-plugin-image";

const CustomPlaceholder = () => (
  <Placeholder
    fallback="data:image/svg+xml,%3Csvg..."
    className="custom-placeholder"
    style={{ backgroundColor: "#f0f0f0" }}
  />
);