Images in GraphQL

Decoupla CMS provides a flexible and efficient way to manage images, offering a rich GraphQL API for retrieving and transforming them. This article will guide you through using the image field in your Decoupla CMS GraphQL API, highlighting its capabilities and usage.

Once an image is uploaded, it will be stored publicly on CloudFlare's R2, ensuring a smooth delivery to the clients.

Image Field Structure

Every image within your Decoupla CMS, when accessed via the GraphQL API, exposes the following fields:

• byteSize: Int!: The size of the original image in bytes.
• format: ImageFormat!: The format of the original image (e.g., AVIF, JPG, PNG, WEBP).
• height: Int!: The height of the original image in pixels.
• id: String!: A unique identifier for the image.
• output(format: ImageFormat, height: Int, width: Int): ImageOutput!: A field for retrieving transformed versions of the image.
• width: Int!: The width of the original image in pixels.

The ImageOutput type, returned by the output field, provides the following information about the transformed image:

• byteSize: Int!: The size of the transformed image in bytes.
• format: ImageFormat!: The format of the transformed image.
• height: Int!: The height of the transformed image in pixels.
• id: String!: A unique identifier for the transformed image.
• url: String!: The URL of the transformed image.
• width: Int!: The width of the transformed image in pixels.

The ImageFormat enum supports the following values: AVIF, SVG, JPG, PNG, and WEBP.

Basic Image Retrieval

To retrieve basic information about an image, you can use a query like this:

query {
  post {
    node {
      featuredImage {
        id
        width
        height
        format
        byteSize
        output {
          url
        }
      }
    }
  }
}

Replace Post and featuredImage with your content type and image field names. This query retrieves the id, width, height, format, byteSize, and a URL to the original uploaded image of the featured image from the first matching post.

Image Transformations

The output field allows you to request transformed versions of your images.

Specifying Format

To convert an image to a specific format, provide the format argument:

query {
  post {
    node {
      featuredImage {
        output(format: WEBP) {
          url
          format
        }
      }
    }
  }
}

This query retrieves the URL and format of the featured image converted to WEBP.

Specifying Dimensions

To resize an image, provide the height and/or width arguments:

query {
  post {
    node {
      featuredImage {
        output(width: 300) {
          url
          width
          height
        }
      }
    }
  }
}

This query retrieves the URL, width, and height of the featured image resized to 300 pixels wide, with the height adjusted proportionally.

If either width or height is not specified or is set to 0, the image will be resized proportionally.

Default Output

If no arguments are provided to the output field, the transformed image will have the same format as the original and will not be resized.

query {
  post {
    node {
      featuredImage {
        output {
          url
          width
          height
          format
        }
      }
    }
  }
}

This query retrieves the url, format, height and width of the image with no transformations applied.

Usage with Gatsby

Since our Gatsby plugin relies on our GraphQL API, all the functionality related to images from our GraphQL API would be available in our Gatsby source plugin as well.

Best Practices

• Use the WEBP or AVIF formats for optimal web performance.
• Resize images to the required dimensions to reduce file size and improve loading times.
• Leverage the GraphQL API to dynamically generate image variations based on your application's needs.