Transform images
This feature is deprecated
Netlify’s Large Media service is deprecated. While Large Media continues to function for sites that currently have it enabled, new Large Media configuration is not recommended. Refer to the deprecation notice in our Support Forums for alternative services and more information.
To avoid the risk of file loss, read our Uninstalling Large Media Support Guide and contact support for assistance turning off Large Media for an existing site.
Netlify offers dynamic image transformation for all JPEG, PNG, and GIF files you have set to be tracked with Netlify Large Media. This means you can upload images at full resolution, then serve exactly the file size you need, when you need it — from gallery thumbnails to responsive images for a variety of screen sizes and pixel densities.
Transformed images are cached for faster performance and reduced transformation count.
# Request transformations
To request an image transformation, add query parameters to the image URL, using ? to start the query string, and & between parameters. Here is a sample image URL with transformation parameters added:
/images/apples.jpg?nf_resize=fit&w=300&h=400
The following query string parameters are available:
nf_resize: parameter specifying the type of transformation requested (required). Accepts the following values:nf_resize=fit: used to resize the image proportionally to fit within the width (w) and height (h) specified. If only one dimension is specified, the other dimension will scale proportionally. Learn more below.nf_resize=smartcrop: used to resize the image to fill the dimensions specified as width (w) and height (h), cropping around an algorithmically determined focal point as needed. Learn more below.
w: parameter that defines the target width of the image in pixels.h: parameter that defines the target height of the image in pixels.
# Examples
The following examples demonstrate how image transformation query parameters can be used to resize images. All examples use the same image, which is very large at full, untransformed size.
# Fit
Setting nf_resize=fit requests that an image be resized to fit within the dimension or dimensions specified.
?nf_resize=fit&w=300
The image above is 300 pixels wide, maintaining the proportions of the original image.
The example below scales to fit a target height:
?nf_resize=fit&h=300
If both height and width are specified, the image is resized to fit within both dimensions. When the image aspect ratio doesn’t match the target dimensions, one image dimension will be shorter than the target.
?nf_resize=fit&w=300&h=300
The resulting image is 300 pixels wide by 200 pixels tall. The image height is shorter than the target height because it scaled proportionally with the width.
# Smartcrop
You can use nf_resize=smartcrop to resize an image to exact dimensions without squashing or stretching. Instead, the image is resized to fill the specified parameters, cropping parts that don’t fit due to differing proportions.
This transformation uses the smartcrop library to center the image on an algorithmically determined focal point before cropping.
The following example uses nf_resize=smartcrop with the same dimensions as the previous example:
?nf_resize=smartcrop&w=300&h=300
The resulting image matches the target dimensions: 300 pixels wide by 300 pixels tall. The height was scaled proportionally to 300 pixels without cropping. Because the proportional width is 450 pixels, 150 pixels of width are cropped to reach 300 pixels.
Rather than cropping 75 pixels equally from both sides, which would result in some fruits being partially out of frame, the smartcrop algorithm selects the fruit and nut arrangement as the focal point, and crops the entire 150 pixels from the left side only.
# Demo site
You can find more image transformation examples in the demo site at netlify-photo-gallery.netlify.app.
The site also includes a query parameter builder, which will generate a query string based on parameters you choose, and apply the resulting transformations to a sample image. You can use it to test and build queries for your own images.
Did you find this doc useful?
Your feedback helps us improve our docs.