Interface RequestInitCfPropertiesImage
anim?: boolean;
background?: string;
blur?: number;
border?: {
color: string;
width: number;
} | {
bottom: number;
color: string;
left: number;
right: number;
top: number;
};
brightness?: number;
compression?: "fast";
contrast?: number;
dpr?: number;
draw?: RequestInitCfPropertiesImageDraw[];
fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
format?: "json" | "avif" | "webp" | "jpeg" | "png";
gamma?: number;
gravity?: "auto" | BasicImageTransformationsGravityCoordinates | "left" | "right" | "top" | "bottom" | "center";
height?: number;
metadata?: "none" | "keep" | "copyright";
origin-auth?: "share-publicly";
quality?: number;
rotate?: 0 | 90 | 180 | 270 | 360;
sharpen?: number;
trim?: {
bottom?: number;
left?: number;
right?: number;
top?: number;
};
width?: number;
}
Hierarchy (view full)
- BasicImageTransformations
- RequestInitCfPropertiesImage
Properties
Optional anim
Optional background
Background color to add underneath the image. Applies only to images with transparency (such as PNG). Accepts any CSS color (#RRGGBB, rgba(…), hsl(…), etc.)
Optional blur
Radius of a blur filter (approximate gaussian). Maximum supported radius is 250.
Optional border
color: string;
width: number;
} | {
bottom: number;
color: string;
left: number;
right: number;
top: number;
}
Adds a border around the image. The border is added after resizing. Border width takes dpr into account, and can be specified either using a single width property, or individually for each side.
Type declaration
color: string
width: number
Type declaration
bottom: number
color: string
left: number
right: number
top: number
Optional 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.
Optional compression
Slightly reduces latency on a cache miss by selecting a quickest-to-compress file format, at a cost of increased file size and lower image quality. It will usually override the format option and choose JPEG over WebP or AVIF. We do not recommend using this option, except in unusual circumstances like resizing uncacheable dynamically-generated images.
Optional 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.
Optional dpr
Device Pixel Ratio. Default 1. Multiplier for width/height that makes it
easier to specify higher-DPI sizes in .
Optional draw
Overlays are drawn in the order they appear in the array (last array entry is the topmost layer).
Optional fit
Resizing mode as a string. It affects interpretation of width and height options:
- 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.
- contain: Resizes to maximum size that fits within the given width and height. If only a single dimension is given (e.g. only width), the image will be shrunk or enlarged to exactly match that dimension. Aspect ratio is always preserved.
- 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 fit.
- crop: The 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's the same as scale-down. For images larger than the given dimensions, it's the same as cover. See also trim.
- 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). Use of this mode is not recommended, as the same effect can be more efficiently achieved with the contain mode and the CSS object-fit: contain property.
Optional format
Output format to generate. It can be:
- avif: generate images in AVIF format.
- webp: generate images in Google WebP format. Set quality to 100 to get the WebP-lossless format.
- json: instead of generating an image, outputs information about the image, in JSON format. The JSON object will contain image size (before and after resizing), source image’s MIME type, file size, etc.
- jpeg: generate images in JPEG format.
- png: generate images in PNG format.
Optional gamma
Increase exposure by a factor. A value of 1.0 equals no change, a value of 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored.
Optional gravity
When cropping with fit: "cover", this defines the side or point that should be left uncropped. The value is either a string "left", "right", "top", "bottom", "auto", or "center" (the default), or an object {x, y} containing focal point coordinates in the original image expressed as fractions ranging from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will crop bottom or left and right sides as necessary, but won’t crop anything from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to preserve as much as possible around a point at 20% of the height of the source image.
Optional height
Maximum height in image pixels. The value must be an integer.
Optional metadata
What EXIF data should be preserved in the output image. Note that EXIF rotation and embedded color profiles are always applied ("baked in" into the image), and aren't affected by this option. Note that if the Polish feature is enabled, all metadata may have been removed already and this option may have no effect.
- keep: Preserve most of EXIF metadata, including GPS location if there's any.
- copyright: Only keep the copyright tag, and discard everything else. This is the default behavior for JPEG files.
- none: Discard all invisible EXIF metadata. Currently WebP and PNG output formats always discard metadata.
Optional origin-
Fetching image from authenticated origin. Setting this property will pass authentication headers (Authorization, Cookie, etc.) through to the origin.
Optional quality
Quality setting from 1-100 (useful values are in 60-90 range). Lower values make images look worse, but load faster. The default is 85. It applies only to JPEG and WebP images. It doesn’t have any effect on PNG.
Optional rotate
Number of degrees (90, 180, 270) to rotate the image by. width and height options refer to axes after rotation.
Optional sharpen
Strength of sharpening filter to apply to the image. Floating-point number between 0 (no sharpening, default) and 10 (maximum). 1.0 is a recommended value for downscaled images.
Optional trim
bottom?: number;
left?: number;
right?: number;
top?: number;
}
An object with four properties {left, top, right, bottom} that specify a 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.
Type declaration
Optionalbottom?: numberOptionalleft?: numberOptionalright?: numberOptionaltop?: number
Optional width
Maximum width in image pixels. The value must be an integer.
Whether to preserve animation frames from input files. Default is true. Setting it to false reduces animations to still images. This setting is recommended when enlarging images or processing arbitrary user content, because large GIF animations can weigh tens or even hundreds of megabytes. It is also useful to set anim:false when using format:"json" to get the response quicker without the number of frames.