Assets

The Asset model is included with every project, can be modified with custom Field Types, and are localized by default, but cannot be deleted.

While most commonly used for photos, can support any file type including audio files, zip files, and more.

The Asset type extends the system fields.

Fetching AssetsAnchor

Hygraph automatically generates 4 query types for assets. These are:

  • asset
  • assets
  • assetVersion
  • assetsConnection

These queries work just like regular queries, and can be filtered by their fields.

Referencing AssetsAnchor

While you can query for individuals assets, or fetch all and filter, order, and paginate, assets are best used when related to another model.

When extending the Hygraph schema with your own models, the Asset field type exposes all of the available transformations below.

For example, imagine you have a Product model with a one to many reference to assets, as images, you can query any of the system fields here also.

{
product(where: { slug: "..." }) {
images {
url
height
width
}
}
}

TransformationsAnchor

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

Resize imagesAnchor

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 typeAnchor

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 transformsAnchor

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 transformsAnchor

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 transformsAnchor

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 } } })
}
}
}

Uploading AssetsAnchor

Hygraph supports uploading assets via HTTP. You'll need a Permanement Auth Token with Mutations API access enabled to upload by file, or URL.

Assets are treated just like any other content entry, so they are automatically bound to the environment, and authorization settings of your project.

You must append /upload to your project API endpoint when uploading assets. For example, https://[region].graphcms.com/v2/[projectId]/[environment]/upload.

Upload by fileAnchor

Uploaded files must be no bigger than 100mb.

Upload by remote URLAnchor

You can also upload files by providing a remote URL, instead of a file.

Updating AssetsAnchor

Since assets are a system model, and automatically added to every project, you can extend them with your own custom fields.

These fields can be updated using GraphQL mutations. For example, some users add a caption field to assets:

mutation {
updateAsset(where: { id: "..." }, data: { caption: "..." }) {
id
}
}

Learn more about Mutations.

Deleting AssetsAnchor

Hygraph exposes a deleteAsset mutation that you can use to delete any unwanted assets.

Simply pass the id of the asset you want deleted:

mutation {
deleteAsset(where: { id: "..." }) {
id
}
}

Learn more about Mutations.

Publishing assetsAnchor

Since Assets are a system model, they also come with publishing capabilities. You can use GraphQL mutations to publish or unpublish your assets, to and from content stages.

Learn more about publishing to content stages.

Localized assetsAnchor

Since assets are localized by default, you can upload a file for your project locales.

Learn more about mutating localized content.

Embedded typesAnchor

Assets can be embedded into the Rich Text Field Type via a configuration setting. On the API side, we create a union relation that references the selected model.