We just launched our new Hygraph Studio in beta. Learn more

Hygraph
Docs

Asset transformations

#Overview

When fetching assets, you can pass an optional transformation argument to the url field.

#Hygraph Asset Management

#Auto image

This document transformation uses the auto_image parameter to determine which mimetype to serve based on the browsers preference.

ArgDescription
auto_imageDetermines which mimetype to serve based on the browsers preference. We either send back a webp or an avif, depending on the Accept request header. Without an Accept header, we use jpg as fallback.

For example:

#Blur

This transformation uses the blur parameter to blur your image.

ArgDescription
amountBlur effect amount. The value must be an integer from 0 to 20.

For example, we can query all assets, and blur images to an amount of 4:

#Border

This transformation uses the border parameter to control the width, color and background of your image borders.

ArgDescription
widthBorder width. The value must be an integer from 1 to 1000.
colorBorder color. The value must be a hexadecimal or shortened hexadecimal color code.
backgroundBorder color. The value must be a hexadecimal or shortened hexadecimal color code, or a supported color name. See table below.

For example, we can query all assets, and set the image borders using our chosen characteristics:

#Compress

This transformation compresses PNG & JPG files.

ArgDescription
compressImage compression. You can choose to compress the metadata as well by passing true or false.

For example, we can query all assets, and compress images along with their metadata:

#Crop

This transformation uses the crop parameter to crop images by entering coordinates and crop dimensions:

  • The starting points for X and Y coordinates are [0,0], aligning with the top-left corner of the image.
  • The width and height parameters determine the size in pixels of the cropping rectangle. The output will include only the portion of the image within the designated crop area.
ArgDescription
xThe x coordinate of the image. The value must be an integer from 0 to 10000.
yThe y coordinate of the image. The value must be an integer from 0 to 10000.
widthThe width in pixels to resize the image to. The value must be an integer from 1 to 10000.
heightThe height in pixels to resize the image to. The value must be an integer from 1 to 10000.

For example, we can query all assets, and crop images:

#Quality

Use the quality parameter to set the quality of your image without risking generating a larger file.

ArgDescription
valueThe quality value of the image. The value must be an integer from 1 to 100.

For example, we can query all assets, and set the image quality to 50:

#Resize

This transformation uses the resize parameter to adjust the image height, width and fit.

The image takes the following arguments:

ArgTypeDescription
widthIntThe width in pixels to resize the image to. The value must be an integer from 1 to 10000.
heightIntThe height in pixels to resize the image to. The value must be an integer from 1 to 10000.
fitImageFitThe default value for this parameter is clip. Check out the following table to look at all possible values.

The ImageFit takes one of the following values:

ValueDescription
clipResizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.
cropResizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.
scaleResizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method.
maxResizes the image to fit within the parameters, but as opposed to fit:clip will not scale the image if the image is smaller than the output size.

For example, we can query all assets, and resize images:

#Sharpen

This transformation uses the sharpen parameter to sharpen your image.

ArgDescription
amountSharpen effect amount. The value must be an integer from 0 to 20.

For example, we can query all assets, and sharpen images to an amount of 2:

#File type conversion

The following table shows the original file type you'd be changing from, and the possible formats you'd change it into. In each case, it indicates whether it's possible - with a checkmark - or if it's not - with a cross.

Input typeAvailable output formatsMimetype
AVIFJPG, PNG, WEBP, GIF, TIFFimage/avif
BMPJPG, PNG, SVG, WEBP, GIF, TIFF, AVIFimage/bmp
GIFJPG, PNG, SVG, WEBP, TIFF, AVIFimage/gif
JPGPNG, SVG, WEBP, GIF, TIFF, AVIFimage/jpg
PDFJPG, GIF, WEBP, TIFF, AVIFapplication/pdf
PNGJPG, SVG, WEBP, GIF, TIFF, AVIFimage/png
SVGJPG, PNG, WEBP, GIF, TIFF, AVIFimage/svg+xml
TIFFJPG, PNG, SVG, WEBP, GIF, AVIFimage/tiff
WEBPJPG, PNG, SVG, GIF, TIFF, AVIFimage/webp

For example, we can query all assets, and convert the images to JPG:

#URL transformations

It is possible to do URL transformations without using the API. You can do this by using the regular URL of an asset and then placing the transformation syntax in it.

You would place the transformation here:

https://REGION.graphassets.dev/ENV_ID/<Transformations go here>/HANDLE

The following example uses resize:

https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/HANDLE

You can also chain the transformations. The following example uses resize and sharpen:

https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/sharpen=amount:2/HANDLE

#Legacy asset system

#Resize images

The image takes the following arguments:

ArgTypeDescription
widthIntThe width in pixels to resize the image to. The value must be an integer from 1 to 10000.
heightIntThe height in pixels to resize the image to. The value must be an integer from 1 to 10000.
fitImageFitThe default value for the fit parameter is clip.

The ImageFit takes one of the following values:

ValueDescription
clipResizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.
cropResizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.
scaleResizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method.
maxResizes the image to fit within the parameters, but as opposed to fit:clip will not scale the image if the image is smaller than the output size.

For example, we can query all assets, and resize images:

{
assets {
url(
transformation: {
image: { resize: { width: 50, height: 50, fit: clip } }
}
)
}
}

#Convert file type

Depending on the asset type you're dealing with, it's possible to transform the output to another file type by passing a format value.

Current file typeAvailable output formats
PDFjpg, odp, ods, odt, png, svg, txt, webp
DOCdocx, html, jpg, odt, pdf, png, svg, txt, webp
DOCXdoc, html, jpg, odt, pdf, png, svg, txt, webp
ODTdoc, docx, html, jpg, pdf, png, svg, txt, webp
XLSjpg, pdf, ods, png, svg, xlsx, webp
XLSXjpg, pdf, ods, png, svg, xls, webp
ODSjpg, pdf, png, xls, svg, xlsx, webp
PPTjpg, odp, pdf, png, svg, pptx, webp
PPTXjpg, odp, pdf, png, svg, ppt, webp
ODPjpg, pdf, png, ppt, svg, pptx, webp
BMPjpg, odp, ods, odt, pdf, png, svg, webp
GIFjpg, odp, ods, odt, pdf, png, svg, webp
JPGjpg, odp, ods, odt, pdf, png, svg, webp
PNGjpg, odp, ods, odt, pdf, png, svg, webp
WEBPjpg, odp, ods, odt, pdf, png, svg, webp
TIFFjpg, odp, ods, odt, pdf, png, svg, webp
AIjpg, odp, ods, odt, pdf, png, svg, webp
PSDjpg, odp, ods, odt, pdf, png, svg, webp
SVGjpg, odp, ods, odt, pdf, png, webp
HTMLjpg, odt, pdf, svg, txt, webp
TXTjpg, html, odt, pdf, svg, webp

For example, let's transform all assets to PDFs:

{
assets {
url(transformation: { document: { output: { format: pdf } } })
}
}

#Validating transforms

We provide a validation field you can enable to check the combination of transform arguments are valid.

For example, you may query a video, and request to change the file type to pdf. validateOptions: true will warn you that this is not permitted.

{
assets {
url(
transformation: {
document: { output: { format: pdf } }
validateOptions: true
}
)
}
}

#Combining transforms

It is possible to combine both transformation arguments:

{
assets {
url(
transformation: {
image: { resize: { width: 50, height: 50, fit: clip } }
document: { output: { format: png } }
validateOptions: true
}
)
}
}

#Alias transforms

GraphQL aliases are great for querying the same asset url with multiple transformations.

For example, you could transform product images to include a thumbnail.

{
products {
images {
thumbnail: url(
transformation: {
image: { resize: { width: 50, height: 50, fit: clip } }
document: { output: { format: png } }
}
)
url(transformation: { document: { output: { format: png } } })
}
}
}