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.

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,
  },
})

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, height, quality }) {
  return `https://${projectId}.supabase.co/storage/v1/${src}?width=${width}&height=${
    height || 0
  }&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#