Storage Image Transformations

Supabase Storage offers the functionality to transform and resize images dynamically. Any image stored in your buckets can be transformed and optimized for fast delivery.

note

Image Resizing is currently enabled for Pro plan and above.

Get a public URL for a transformed image#

You can pass a transform option to the functions you are currently using to interact with your objects. This returns the public URL that serves the resized image.

supabase.storage.from('bucket').getPublicUrl('image.jpg', {
  transform: {
    width: 500,
    height: 600,
  },
})

An example URL could look like this:

https://project_id.supabase.co/storage/v1/render/image/public/bucket/image.jpg?width=500&height=600

Signing URLs with transformation options#

To share a transformed image for a fixed amount of time, provide the transform options when you create the signed URL:

supabase.storage.from('bucket').createSignedUrl('image.jpg', 60000, {
  transform: {
    width: 200,
    height: 200,
  },
})

The transformation options are embedded into the token—they cannot be changed once signed.

Downloading images#

To download a transformed image, pass the transform option to the download function.

supabase.storage.from('bucket').download('image.jpg', {
  transform: {
    width: 800,
    height: 300,
  },
})

Automatic Image Optimisation (WebP)#

When using the image transformation API we will automatically find the best format supported by the browser and return that to the client, without any code change. For instance, if you use Chrome when viewing a jpeg image and using transformation options, you'll see that the content-type returned is webp.

As a result, this will lower the bandwidth that you send to your users and your application will load much faster.

note

We currently only support WebP. AVIF support will come in the near future

Disabling automatic optimisation:

In case you'd like to return the original format of the image and opt-out from the automatic image optimization detection, you can pass the format=origin parameter when requesting a transformed image, this is also supported in the JavaScript SDK starting from v2.2.0

await storage.from('bucket').download('image.jpeg', {
  transform: {
    width: 200,
    height: 200,
    format: 'origin',
  },
})

NextJS Loader#

You can use Supabase Image Transformation to optimise your NextJS images using a custom Loader.

To get started, create a supabase-image-loader.js file in your NextJS project which exports a default function:

const projectId = '' // your supabase project id
export default function supabaseLoader({ src, width, quality }) {
  return `https://${projectId}.supabase.co/storage/v1/render/image/public/${src}?width=${width}&quality=${
    quality || 75
  }`
}

In your nextjs.config.js file add the following configuration to instruct NextJS to use our custom loader

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './supabase-image-loader.js',
  },
}

At this point you are ready to use the Image component provided by NextJS

import Image from 'next/image'
const MyImage = (props) => {
  return <Image src="bucket/image.png" alt="Picture of the author" width={500} height={500} />
}

Transformation options#

We currently support a few transformation options focusing on resizing and cropping images.

Resizing#

You can use width and height parameters to resize an image to a specific dimension. If only one parameter is specified, the image will be resized and cropped, maintaining the aspect ratio.

Modes#

You can use different resizing modes to fit your needs, each of them uses a different approach to resize the image:

Use the resize parameter with one of the following values:

cover : resizes the image while keeping the aspect ratio to fill a given size and crops projecting parts. (default)
contain : resizes the image while keeping the aspect ratio to fit a given size.
fill : resizes the image without keeping the aspect ratio.

Example:

supabase.storage.from('bucket').download('image.jpg', {
  transform: {
    width: 800,
    height: 300,
    resize: 'contain', // 'cover' | 'fill'
  },
})

Limits#

Width and height must be an integer value between 1-2500.
The image size cannot exceed 25MB.
The image resolution cannot exceed 50MP.

Supported Image Formats#

Format	Extension	Source	Result
PNG	`png`	☑️	☑️
JPEG	`jpg`	☑️	☑️
WebP	`webp`	☑️	☑️
AVIF	`avif`	☑️	☑️
GIF	`gif`	☑️	☑️
ICO	`ico`	☑️	☑️
SVG	`svg`	☑️	☑️
HEIC	`heic`	☑️	❌
BMP	`bmp`	☑️	☑️
TIFF	`tiff`	☑️	☑️

Self Hosting#

Our solution to image resizing and optimisation can be self-hosted as with any other Supabase product. Under the hood we use the awesome Imgproxy

Imgproxy Configuration:

Simply deploy an imgproxy container with the following configuration:

imgproxy:
  image: darthsim/imgproxy
  environment:
    - IMGPROXY_ENABLE_WEBP_DETECTION=true
    - IMGPROXY_JPEG_PROGRESSIVE=true

Note: make sure that this service can only be reachable within an internal network and not exposed to the public internet

Storage API Configuration:

Once Imgproxy is deployed we need to configure a couple of environment variables in your self-hosted storage-api service as follows:

ENABLE_IMAGE_TRANSFORMATION=true
IMGPROXY_URL=yourinternalimgproxyurl.internal.com

Edit this page on GitHub