Uploads

Last updated on June 26, 2024.

Uploads are used to store the URL and metadata of a file that you uploaded.

Defining uploads

You can define uploads by adding a database field with set to , for example:

Options

The database field takes an extra parameter, which allows you to configure it.

Option Description
The file is made publicly available if set to (default). It is automatically generated by GraphQL when you provide the argument to the field in the PropertiesInterface GraphQL interface. A signature generated on the server side is needed to access the file if set to .
Allows you to set server-side validation for minimum (using the key) and maximum file size (using the key) in kilobytes. For example, will set the max input file size (not the generated version) to 2MB.
Allows you to define up to 10 versions of the image. You can define multiple processing instructions for each version - compression, resizing, etc. Visit the section on version options in this article, just after this table. This option is ignored if the uploaded file is not an image.
Allows you to set the Cache-Control header returned with the file. Default is
Allows you to set the Content-Disposition header. The default is  which you can change to an .

Versions

Versions are defined in yml as an array. Each element must have a and a list of options you want to use. Please note that not all combinations make sense. An example configuration might look like this:

Output

Output parameter options are detailed in the table below:

Output option Description
[String]Force a file extension for an output image; leave blank if you want to keep the format of the original image.
[Int]

Quality of the output. being the best (and largest in terms of size). Keep in mind compression has different effects on different formats. Default values are as follows:

  • PNG:
  • WEBP:
  • JPEG:
[Boolean] Only - use progressive (interlace) scan. Default:

Resize

Resize parameter options are outlined in the table below:

Resize optionDescription
[Int] The width that the user passed as a reference. Other parameters are left to determine the size (like height) if left undefined.
[Int] The height that the user passed as a reference. Other parameters are left to determine the size (like width) if left undefined.
[String]

This option controls how the image should be resized to fit both provided dimensions. The following options are available:

  • : Crop to cover both provided dimensions (the default).
  • : Embed within both provided dimensions.
  • : Ignore the input aspect ratio and stretch to both provided dimensions.
  • : Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to those specified.
  • : Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified. Some of these values are based on the object-fit CSS property.
[String]

Position to use when the is set to or . Default value: . The following options are available:

[String|Object] Background colour used when using a fit set to . This option is parsed by the colour module and defaults to black without transparency. Default values are: or .
[Boolean] Do not enlarge if the width or height exceeds the specified dimensions. Default value:

Manipulate

Manipulate parameter options are detailed in the following table:

Manipulate optionDescription
[Boolean] Convert to 8-bit greyscale; 256 shades of grey. Default:
[Int|Float] (0.3 - 1000) Value representing the sigma of the Gaussian mask, where
[String|Object] Default: or

Sending the upload to a server

To store an upload, you must first upload a physical file directly to S3. When you do it successfully, you will receive a URL to the actual file - you need to store this URL in the property.

Fetching an upload from a server

To fetch the URL of the uploaded image, use the argument to generate the signature needed to access the private file. The signature automatically expires after the number of seconds you specify. Please note that you cannot access the URL when you fetch all properties at once using in your GraphQL query. This is because the URL is generated on the fly inside the method.

Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.