Transform Files
Directus allows you to transform assets using URL query parameters. You can pass these as either query parameters to the assets endpoint. If a processed asset does not yet exist, it is dynamically generated, stored, and returned.
Custom Transformations
| Parameter | Description |
|---|---|
width | How wide the image is in pixels. |
height | How high the image is in pixels. |
quality | The overall image quality (1 to 100), defaults to 100 if omitted. The higher the value, the larger the image size. The lower the value, the more compression artifacts are in the image. |
withoutEnlargement | Disable automatically upscaling the image (true) |
format | What file format to return the image in. One of auto, jpg, png, webp, tiff auto default if omitted, Will try to format it in webp or avif if the browser supports it, otherwise it will fallback to jpg. |
fit | How the image should fit into the provided dimensions, values including:
|
When transforming an image with
width and/or height parameters, the focal point is taken from the focal_point_x and focal_point_y coordinate values stored in the file object, cropping the image around these. This defaults to the image's centre.GET /assets/c984b755-e201-497e-b0a7-24156ad9c7e0
?width=300
&height=300
&quality=50
&fit=contain
Advanced Transformations
Directus allows full access to the Sharp API, giving you access to more complex image transformations.
This is done using the transforms parameter, whose value consists of a two dimensional array. Each sub-array contains the name of the operation, followed by its arguments: [["operation1", …arguments], ["operation2", …otherArguments]].
When calling the REST API, datatypes like booleans need to be passed as strings.
| sharp API Call | transforms Equivalent |
|---|---|
.rotate(90) | [["rotate", 90]] |
.rotate(90).blur(10).tint(255, 0, 255) | [["rotate", 90], ["blur", 10], ["tint", "rgb(255, 0, 255)"]] |
negate({lower: 10, upper: 50}) | [["negate", {"lower": 10, "upper": 50}]] |
GET /assets/c984b755-e201-497e-b0a7-24156ad9c7e0
?transforms=[["rotate", 90],["blur", 10],["tint", "rgb(255, 0, 255)"], ["negate", {"lower": 10, "upper": 50}]]
Custom and advanced transformations can also be used in conjunction.
GET /assets/c984b755-e201-497e-b0a7-24156ad9c7e0
?transforms=[["flip"]]
&fit=cover
&width=300
&height=100
Preset Transformations
In order to mitigate the creation a large number of files, you can restrict the transformations to a set of presets. You can create your own storage asset preset in the "Settings" section of your project's settings.
The following options are available:
- Allowed Transformations: for enabling, disabling, or limiting image transformations.
- Default Folder: sets the default folder where new assets are added. This does not affect existing files. Be aware that fields may override this value.
- Transformation Presets: sets a specific image transformation configuration to simplify requests or limit usage.
- Key: sets unique identifier allowing faster and easier image transformation requests.
- Fit: contain (keeps aspect ratio), Cover (exact size), Fit Inside, or Fit Outside.
- Width: sets the width of the image.
- Height: sets the height of the image.
- Quality: adjusts the compression or quality of the image.
- Upscaling: when enabled, images won't be upscaled.
- Format: changes the output format.
- Additional Transformations: adds additional transformations using Sharp.
You can then use this key as a parameter to when requesting a file to apply the preset.