What is Xata?
Command line interface
Dedicated clusters
Migrations
PR based workflow
beta
Usage metrics
beta
Installation & API keys
Getting records
Creating records
Updating records
Deleting records
Filtering records
Transactions
Searching records
Vector searching records
beta
Aggregations
beta
Summarize
Ask AI
File attachments
Image transformations
CSV
Airbyte
beta
Auth JS
Cloudflare Workers
GitHub
LangChain
Netlify
OAuth 2
alpha
Vercel
Zapier
Available regions
Pricing
Service level agreement
Limitations
Branch inactivity
Support
Docs contribution guide

Image transformations

Edit on GitHub

Xata supports transformations for images stored in Xata's xata_file and xata_file_array column types.

Transformations are specified by modifying the File's URL by adding /transform/height=100,width=200/{fileId}

#

Example

Original image URL:

https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94

Transformed image URL:

https://us-east-1.storage.xata.sh/transform/rotate=180,height=100,format=webp/4u1fh2o6p10blbutjnphcste94

Original

original

Transformed

transformed

#

SDK transformation helpers

Our SDKs provide helpers to apply transformations to image URLs.

import { transformImage } from '@xata.io/client';

// Apply transformations to a Xata image URL
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  height: 100,
  rotate: 180,
  format: 'webp'
});
// => https://us-east-1.storage.xata.sh/transform/rotate=180,height=100,format=webp/4u1fh2o6p10blbutjnphcste94

// Or shorthand when you have a record:
const record = await xata.db.movies.read('rec_xyz');

const { url } = record.movieThumbnail.transform({
  height: 100,
  rotate: 180,
  format: 'webp'
});

console.log(url);
// => "https://us-east-1.xata.sh/transform/height=100,rotate=180,format=webp/file/09p6sdj2dopigqfipg3a6i7kilsliolv27no4penf5taohum9gf5f7aj01iteuclfpqfsqc1nfepjvq4i1alj0i7siup94dmikj23bmc51cb00mgj7f6i9d1d84o2bvskp4rqit1nsu004tcfjc3u6asmk"

See our supported transformations.

#

Image metadata

You can retrieve the image metadata of a file by adding /transform/format=json/ to an image URL. This will return JSON containing the metadata for the image.

Example:

https://us-east-1.storage.xata.sh/transform/format=json/4u1fh2o6p10blbutjnphcste94

{
  "width": 300,
  "height": 200,
  "original": {
    "file_size": 29476,
    "width": 300,
    "height": 200,
    "format": "image/jpeg"
  }
}
import { transformImage } from '@xata.io/client';

// Apply transformations to a Xata image URL
const metadataUrl = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  format: 'json',
  height: 100
});
// => https://us-east-1.storage.xata.sh/transform/format=json,height=100/4u1fh2o6p10blbutjnphcste94

const response = await fetch(metadataUrl);
const metadata = await response.json();

// Or shorthand when you have a record:
const record = await xata.db.movies.read('rec_xyz');

const result = record.movieThumbnail.transform({
  height: 100,
  rotate: 180,
  format: 'webp'
});

console.log(result);
/*
  {
    url: "https://us-east-1.xata.sh/transform/height=100,rotate=180,format=webp/file/09p6sdj2dopigqfipg3a6i7kilsliolv27no4penf5taohum9gf5f7aj01iteuclfpqfsqc1nfepjvq4i1alj0i7siup94dmikj23bmc51cb00mgj7f6i9d1d84o2bvskp4rqit1nsu004tcfjc3u6asmk",
    metadataUrl: "https://us-east-1.xata.sh/transform/height=100,rotate=180,format=webp,format=json/file/09p6sdj2dopigqfipg3a6i7kilsliolv27no4penf5taohum9gf5f7aj01iteuclfpqfsqc1nfepjvq4i1alj0i7siup94dmikj23bmc51cb00mgj7f6i9d1d84o2bvskp4rqit1nsu004tcfjc3u6asmk"
  }
*/

#

Transformations

The following transformations are available:

#

anim

Removes animation frames from input files. Default is set to true. Setting it to false reduces animations to still images. You will also need to pass at least one other transformation, like format: 'auto', for it to take effect.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/ai4u0uoq297518gmuqboschtcs', {
  anim: false,
  format: 'auto'
});

Original

original

Transformed

transformed

#

background

Adds a background color beneath the image. Applies to images with transparency. Accepts any CSS color, such as #RRGGBB and rgba(…).

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/a3r97ge71h3od25glq8ook1vg8', {
  background: 'pink'
});

Original

original

Transformed

transformed

#

blur

Adds a blur radius ranging from 1 (slight blur) to 250 (maximum).

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  blur: 20
});

Original

original

Transformed

transformed

#

brightness

Increase brightness by a factor. A value of 1.0 equals no change, a value of 0.5 equals half brightness, and a value of 2.0 equals twice as bright. 0 is ignored.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  brightness: 0.5
});

Original

original

Transformed

transformed

#

compression

This marginally reduces latency in case of a cache miss, by selecting the fastest-compressing file format. However, this comes at the expense of larger file sizes and diminished image quality. The only option is fast. It will usually override the format option and choose JPEG over WebP or AVIF.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  compression: 'fast'
});

Original

original

Transformed

transformed

#

contrast

Increase contrast by a factor. A value of 1.0 equals no change, a value of 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is ignored.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  contrast: 0.5
});

Original

original

Transformed

transformed

#

download

Depending on the file type, some browsers preview the file instead of downloading it. Setting the download property will make sure the browser always downloads the file. The value allows you to assign a name, and optionally an extension to the file that will be downloaded.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  download: 'xata-cat.jpg',
  format: 'jpeg'
});

#

dpr

This refers to the Device Pixel Ratio (DPR). The default is 1. This is a multiplier (similar to a flat scale) for width/height that makes it easier to specify higher-DPI sizes in img srcset. dpr needs to be used in tandem with a dimension transform to take effect.

import { transformImage } from '@xata.io/client';

// Note that the rendered example is actually 400px even though the original was 200px
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  dpr: 2,
  height: 200,
  fit: 'contain'
});

Original

original

Transformed

transformed

#

fit

Affects interpretation of width and height. All resizing modes preserve aspect ratio.

#

contain

Image will be resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio. If you only provide a single dimension (for example, only width), the image will be shrunk or enlarged to exactly match that dimension.

import { transformImage } from '@xata.io/client';

// Note that the rendered example retains the original aspect-ratio
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'contain'
});

Original

original

Transformed

transformed
import { transformImage } from '@xata.io/client';

// Note that the rendered example retains the original aspect-ratio, but doesn't grow beyond the original size
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 250,
  height: 250,
  fit: 'contain'
});

Original

original

Transformed

transformed

#

scale-down

Similar to contain, but the image is never enlarged. If the image is larger than given width or height, it will be resized. Otherwise its original size will be kept.

import { transformImage } from '@xata.io/client';

// Notice that the rendered example scales down properly because the source is larger
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'scale-down'
});

Original

original

Transformed

transformed
import { transformImage } from '@xata.io/client';

// Notice that the rendered example does not grow beyond it's original size
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 600,
  height: 400,
  fit: 'scale-down'
});

Original

original

Transformed

transformed

#

cover

Resizes (shrinks or enlarges) to fill the entire area of width and height. If the image has an aspect ratio different from the ratio of width and height, it will be cropped to

import { transformImage } from '@xata.io/client';

// Notice that the rendered example is a perfect square
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'cover'
});

Original

original

Transformed

transformed
import { transformImage } from '@xata.io/client';

// Notice that the rendered example is a perfect square that enlarges past its original size
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 250,
  height: 250,
  fit: 'cover'
});

Original

original

Transformed

transformed

#

crop

Image will be shrunk and cropped to fit within the area specified by width and height. The image will not be enlarged. For images smaller than the given dimensions, it is the same as scale-down. For images larger than the given dimensions, it is the same as cover.

import { transformImage } from '@xata.io/client';

// Notice that the rendered example crops to a square because it is below the original size
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'crop'
});

Original

original

Transformed

transformed
import { transformImage } from '@xata.io/client';

// Notice that the rendered example does not become a square, and does not grow above the original size
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 500,
  height: 500,
  fit: 'crop'
});

Original

original

Transformed

transformed

#

pad

Resizes to the maximum size that fits within the given width and height, and then fills the remaining area with a background color (white by default). This mode is not recommended, since you can achieve the same effect more efficiently with the contain mode and the CSS object-fit contain property.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 250,
  height: 250,
  fit: 'pad',
  background: 'pink'
});

Original

original

Transformed

transformed

#

format

Converts the format of the retrieved image.

  • auto Will serve the WebP or AVIF format to browsers that support it. If this option is not specified, a standard format like JPEG or PNG will be used.
  • avif Generate images in AVIF format if possible (with WebP as a fallback).
  • webp Generate images in Google WebP format. Set the quality to 100 to get the WebP lossless format.
  • json Instead of generating an image, outputs metadata about the image in JSON format.
import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  format: 'webp'
});

Original

original

Transformed

transformed

Here is an example of outputting JSON, which will give you dimensions of the transformed image along with details from the original.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  height: 100,
  format: 'json'
});

Check the resulting JSON at https://us-east-1.storage.xata.sh/transform/format=json,height=100/4u1fh2o6p10blbutjnphcste94

{
  "width": 125,
  "height": 100,
  "original": { "file_size": 22684, "width": 250, "height": 200, "format": "image/jpeg" }
}

#

gamma

Increases exposure by a factor. A value of 1.0 equals no change, a value of 0.5 darkens the image, while a value of 2.0 lightens the image. 0 is ignored.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  gamma: 0.5
});

Original

original

Transformed

transformed

#

gravity

When cropping with fit: "cover" and fit: "crop", this parameter defines the side or point that should not be cropped. Available options are:

  • auto Selects focal point based on saliency detection (using maximum symmetric surround algorithm).
  • side A side ("left", "right", "top", "bottom") or coordinates specified on a scale from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. The X and Y coordinates are separated by lowercase x in the URL format. For example, 0x1 means left and bottom, 0.5x0.5 is the center, 0.5x0.33 is a point in the top third of the image.
import { transformImage } from '@xata.io/client';

// Crop from right
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'cover',
  gravity: 'right'
});

Original

original

Transformed

transformed
import { transformImage } from '@xata.io/client';

// Crop from left and bottom
const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100,
  height: 100,
  fit: 'cover',
  gravity: {
    x: 0,
    y: 1
  }
});

Original

original

Transformed

transformed

#

height

Specifies maximum height of the image in pixels. Exact behavior depends on the fit mode.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  height: 100
});

Original

original

Transformed

transformed

#

metadata

Controls amount of invisible metadata (EXIF data) that should be preserved. Color profiles and EXIF rotation are applied to the image even if the metadata is discarded. Note that if the Polish feature is enabled, all metadata may have been removed already and this option will have no effect. Options are:

  • keep Preserves most of EXIF metadata, including GPS location if present.
  • copyright Discards all metadata except EXIF copyright tag. This is the default behavior for JPEG images.
  • none Discards all invisible EXIF metadata. Currently, WebP and PNG output formats always discard metadata.
import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  metadata: 'none'
});

#

quality

Specifies quality for images in JPEG, WebP, and AVIF formats. The quality is in a 1-100 scale, but useful values are between 50 (low quality, small file size) and 90 (high quality, large file size). 85 is the default.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  quality: 50
});

Original

original

Transformed

transformed

#

rotate

Specifies number of degrees (90, 180, or 270) to rotate the image by. Width and height options refer to axes after rotation.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  rotate: 90
});

Original

original

Transformed

transformed

#

sharpen

Specifies strength of sharpening filter to apply to the image. The value is a floating-point number between 0 (no sharpening, default) and 10 (maximum). 1 is a recommended value for downscaled images.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  sharpen: 2
});

Original

original

Transformed

transformed

#

trim

Specifies the number of pixels to cut off on each side. Allows removal of borders or cutting out a specific fragment of an image. Trimming is performed before resizing or rotation. Takes dpr into account.

import { transformImage } from '@xata.io/client';

const transformedUrl = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  trim: {
    top: 20,
    right: 30,
    bottom: 20,
    left: 0
  }
});

Original

original

Transformed

transformed

#

width

Specifies maximum width of the image in pixels. Exact behavior depends on the fit mode.

import { transformImage } from '@xata.io/client';

const url = transformImage('https://us-east-1.storage.xata.sh/4u1fh2o6p10blbutjnphcste94', {
  width: 100
});

Original

original

Transformed

transformed

#

Supported image file types

  • Supported input formats:

    • JPEG
    • PNG
    • GIF (including animations)
    • WebP (no animations)
    • SVG

  • Supported output formats:

    • JPEG
    • PNG
    • GIF (including animations)
    • WebP (including animations)
    • SVG
    • AVIF

On this page

ExampleSDK transformation helpersImage metadataTransformationsanimbackgroundblurbrightnesscompressioncontrastdownloaddprfitcontainscale-downcovercroppadformatgammagravityheightmetadataqualityrotatesharpentrimwidthSupported image file types