Transform images

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 – specifies the type of transformation requested (required). Accepts the following values:
    • nf_resize=fit – resizes the image proportionally to fit within the width (w) and/or height (h) specified. If only one dimension is specified, the other dimension will scale proportionally. Learn more below.
    • nf_resize=smartcrop – resizes 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: defines the target width of the image in pixels
  • h: defines the target height of the image in pixels

Note

Netlify will never scale an image larger than its original resolution. If you need to account for images smaller than expected in your layout, you can handle this in your HTML and CSS.

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

original image scaled to 300px wide

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

original image scaled to 300px tall

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

original image scaled to 300px wide

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

original image scaled to 300px tall, with sides cropped to 300px wide

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.com.

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.

Image transformation: Usage and billing