GraphQL support BETA

WARNING

The GraphQL support in Imager has not been as thouroughly battle-tested as the rest of it, and should be considered beta for the time being.

Imager X comes with some basic support for GraphQL; two directives and a custom query. The imagerTransform directive mimicks the built-in transform directive, you apply it to the url property of an Asset field, supply the arguments for the transform, and Imager will return the URL for the transformed image.

{
  entries (section: "news", orderBy: "dateCreated DESC") {
    title
    ... on news_news_Entry {
      image {
        url @imagerTransform (width: 300, height: 300, mode: "crop", format: "jpg")
      }
    }
  }
}

The directive also takes a return argument, which can be used to get base64 encoded versions back, instead of the URL. It takes one of three possible values, url, base64, dataUri and blurhash (as of Imager X 3.4.0).

{
  entries (section: "news", orderBy: "dateCreated DESC") {
    title
    ... on news_news_Entry {
      image {
        url,
        transform: url @imagerTransform (width: 300, height: 300, mode: "crop", format: "jpg"),
        dataUri: url @imagerTransform (width: 4, height: 4, mode: "crop", format: "gif", return: "dataUri"),
        blurhash: url @imagerTransform (width: 100, height: 100, mode: "crop", format: "jpg", return: "blurhash"),
      }
    }
  }
}

The imagerSrcset works in the same way, but takes the handle for a named transform as its only argument, and returns a srcset string.

{
  entries (section: "news", orderBy: "dateCreated DESC") {
    title
    ... on news_news_Entry {
      image {
        url,
        srcset: url @imagerSrcset (handle:"heroImage")
      }
    }
  }
}

Directives are fine for simple things, but gives you a very limited amount of information back. In addition, services like Gatsby and Gridsome that consumes your GraphQL, doesn't automatically know about them. They need a source plugin that describes how the directives work.

To unlock the real power of GraphQL and Imager, you probably want to use the imagerTransform query. The query takes either an id or an url as argument, along with the handle of a named transform , and let's you return any property on the transformed image.

{
	hero: imagerTransform(id: 340, transform: "heroImage") {
        url,
        width,
        height,
        size,
        extension,
        mimeType
  }
}

You can also (as of Imager 3.5.2) use the imagerTransform query directly on an AssetInterface like this:

{
  entries (section: "news", orderBy: "dateCreated DESC") {
    title
    ... on news_news_Entry {
      image {
        url,
        ... on volume_Asset {
          transform: imagerTransform(transform: "heroImage") {
            width
            height
            url
            mimeType
            size
          }
        }
      }
    }
  }
}

There is still a lot of features in Imager that is not exposed through GraphQL. If you're in need of something, please file a feature request in the repo (opens new window)!