or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced.mdcomponents.mdindex.mdtypes.mdutilities.md
tile.json

index.mddocs/

Gatsby Plugin Image

Gatsby Plugin Image provides responsive images that automatically resize and optimize themselves based on device size and image format support. It offers two main components: GatsbyImage for dynamic images sourced from GraphQL and StaticImage for static images processed at build time, both with advanced features like lazy loading, customizable placeholders, and modern image format support.

Package Information

  • Package Name: gatsby-plugin-image
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install gatsby-plugin-image

Core Imports

import { GatsbyImage, StaticImage, getImage, getSrc } from "gatsby-plugin-image";
import type { IGatsbyImageData, GatsbyImageProps } from "gatsby-plugin-image";

For CommonJS:

const { GatsbyImage, StaticImage, getImage, getSrc } = require("gatsby-plugin-image");

Basic Usage

GatsbyImage with GraphQL

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

const MyComponent = ({ data }) => {
  const image = getImage(data.file);
  
  return (
    <GatsbyImage
      image={image}
      alt="A description of my image"
    />
  );
};

export const query = graphql`
  query {
    file(relativePath: { eq: "hero.jpg" }) {
      childImageSharp {
        gatsbyImageData(width: 800, placeholder: BLURRED)
      }
    }
  }
`;

StaticImage for Static Images

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

const MyComponent = () => (
  <StaticImage
    src="../images/hero.jpg"
    alt="A description of my image"
    placeholder="blurred"
    layout="constrained"
    width={800}
    height={600}
  />
);

Architecture

Gatsby Plugin Image is built around several key components:

  • GatsbyImage Component: Runtime component for displaying optimized images from GraphQL with progressive loading
  • StaticImage Component: Build-time processed static images using Babel transformation
  • Image Utilities: Helper functions for extracting image data and generating image configurations
  • Type System: Comprehensive TypeScript support with type-safe image data structures
  • Layout System: Multiple layout strategies (constrained, fixed, fullWidth) for different use cases
  • Progressive Enhancement: Lazy loading, placeholder support, and format optimization

Capabilities

Image Components

Core React components for displaying optimized images with automatic responsive behavior and performance optimizations.

function GatsbyImage(props: GatsbyImageProps): JSX.Element;
function StaticImage(props: IStaticImageProps): JSX.Element;

Image Components

Image Utilities

Helper functions for extracting image data from GraphQL nodes and generating image configurations for external services.

function getImage(node: ImageDataLike | null): IGatsbyImageData | undefined;
function getSrc(node: ImageDataLike): string | undefined;
function getSrcSet(node: ImageDataLike): string | undefined;
function getImageData<OptionsType>(args: IGetImageDataArgs<OptionsType>): IGatsbyImageData;

Image Utilities

Advanced Features

Art direction support for different images at different screen sizes and integration with external image services.

function withArtDirection(
  defaultImage: IGatsbyImageData,
  artDirected: Array<IArtDirectedImage>
): IGatsbyImageData;

function generateImageData(args: IGatsbyImageHelperArgs): IGatsbyImageData;

Advanced Features

Type Definitions

Complete type definitions for image data structures, component props, and configuration options.

interface IGatsbyImageData {
  layout: Layout;
  width: number;
  height: number;
  backgroundColor?: string;
  images: {
    sources: Array<{
      srcSet: string;
      type: string;
      sizes?: string;
    }>;
    fallback: {
      src: string;
      srcSet: string;
      sizes?: string;
    };
  };
  placeholder?: {
    fallback: string;
  };
}

interface GatsbyImageProps {
  alt: string;
  image: IGatsbyImageData;
  as?: ElementType;
  className?: string;
  imgClassName?: string;
  imgStyle?: CSSProperties;
  backgroundColor?: string;
  objectFit?: CSSProperties["objectFit"];
  objectPosition?: CSSProperties["objectPosition"];
  onLoad?: (event: { wasCached: boolean }) => void;
  onError?: ReactEventHandler<HTMLImageElement>;
  onStartLoad?: (event: { wasCached: boolean }) => void;
}

type Layout = "fixed" | "constrained" | "fullWidth";
type ImageFormat = "jpg" | "png" | "webp" | "avif" | "auto" | "";

Type Definitions