• Keyword: background
• Type: string
This instructs various directives (e.g. the rotate) to use the specified color when filling empty spots in the image.
The argument will be parsed by the color-string library so all color values known from css like rgb, rgba or named colors can be used.
NOTE: This directive does nothing on it's own, it has to be used in conjunction with another directive.
You also cannot set multiple values.
• Example:
import Image from 'foo.jpg?background=#FFFFFFAA'
import Image from 'foo.jpg?background=hsl(360, 100%, 50%)'
import Image from 'foo.jpg?background=rgb(200, 200, 200)'
import Image from 'foo.jpg?background=blue'• Keyword: blur
• Type: float| boolean
Blurs the image. When no argument is provided it performs a fast blur. When an argument between 0.3 and 1000 is provided it performs a more accurate gaussian blur.
• Example:
import Image from 'example.jpg?blur'
import Image from 'exmaple.jpg?blur=0.75'
import Image from 'example.jpg?blur=100'• Keyword: effort
• Type: integer | "max" | "min"
Adjust the effort to spend encoding the image. The effect of effort varies per format, but a lower value leads to faster encoding.
The supported ranges by format:
png: 1 to 10 (default 7)webp: 0 to 6 (default 4)avif/heif: 0 to 9 (default 4)jxl: 3 to 9 (default 7)gif: 1 to 10 (default 7)
The keywords "min" and "max" apply the highest effort value for the given image format.
Search
options.effortin sharp's Output options documentation for details.
• Example:
import highestEffortWebp from 'example.jpg?format=webp&effort=max'
import quicklyGeneratingAvif from 'example.jpg?format=avif&effort=0'• Keyword: fit
• Type: cover | contain | fill | inside | outside
When both a width and height are provided, this directive can be used to specify the method by which the image
should fit.
• Example:
import Image from 'example.jpg?fit=cover'• Keyword: flatten
• Type: boolean
This directive will remove the alpha channel of the image, reducing filesize. Transparent pixels will be merged with the color set by the background directive.
• Keyword: flip
• Type: boolean
Flip the image about the vertical axis. This step is always performed after any rotation.
• Example:
import Image from 'example.jpg?flip'
import Image from 'exmaple.jpg?flip=true'• Keyword: flop
• Type: boolean
Flop the image about the horizontal axis. This step is always performed after any rotation.
• Example:
import Image from 'example.jpg?flop'
import Image from 'exmaple.jpg?flop=true'• Keyword: format
• Type: jxl| heif | avif | jpeg | jpg | png | tiff | webp |
gif
Convert the image into the given format.
NOTE: Converting to the
gifformat requires libvips compiled with support for ImageMagick or GraphicsMagick See The sharp docs for details.
• Example:
import Image from 'example.jpg?format=webp'
import Images from 'example.jpg?format=webp;avif;jxl'• Keyword: grayscale
• Type: boolean
Converts the image to an 8-bit grayscale image.
This directive will convert the image to the
b-wcolorspace, meaning the resulting image will only have one channel.
• Example:
import Image from 'example.jpg?grayscale'
import Image from 'exmaple.jpg?grayscale=true'• Keyword: hue
• Type: integer
Adjusts the images hue rotation by the given number of degrees. Commonly used together with saturation
and brightness.
• Keyword: saturation
• Type: float
Adjusts the images saturation with the given saturation multiplier. Commonly used together with hue and
brightness.
• Keyword: brightness
• Type: float
Adjusts the images brightness with the given brightness multiplier. Commonly used together with hue and
saturation.
• Keyword: invert
• Type: boolean
Produces a 'negative' of the image.
• Example:
import Image from 'example.jpg?invert'
import Image from 'exmaple.jpg?invert=true'• Keyword: kernel
• Type: nearest| cubic | mitchell | lanczos2 | lanczos3
Use this directive to set a different interpolation kernel when resizing the image.
• Keyword: lossless
• Type: boolean
Use lossless compression mode.
Formats that support this directive are:
avif, heif, jxl, and webp
• Example:
import losslessWebp from 'example.jpg?format=webp&lossless';
import losslessAvif from 'example.jpg?format=avif&lossless=true';• Keyword: median
• Type: float| boolean
Applies a median filter. This is commonly used to remove noise from images.
• Example:
import Image from 'example.jpg?median'
import Image from 'exmaple.jpg?median=3'
import Image from 'example.jpg?median=50'• Keyword: normalize
• Type: boolean
'Normalizes' the image by stretching its luminance to cover the full dynamic range. This Enhances the output image contrast.
• Example:
import Image from 'example.jpg?normalize'
import Image from 'exmaple.jpg?normalize=true'• Keyword: position
• Type: top| right top | right | right bottom | bottom | left bottom
| left | left top | north | northeast | east | southeast | south | southwest | west |
northwest | center | centre | cover | entropy | attention
When both width and height are provided AND the fit is one of fit of cover or contain, this directive can be
used to set the position of the image.
See sharps resize options for a detailed explanation of each.
• Keyword: quality
• Type: integer
All formats (except gif) allow the quality to be adjusted by setting this directive.
The argument must be a number between 1 and 100.
See sharps Output options for default quality values.
• Example:
import Image from 'example.jpg?format=webp&quality=100'
import Images from 'example.jpg?format=avif&quality=10;50;75'• Keyword: w
• Type: integer
Resizes the image to be the specified amount of pixels wide. If not given the height will be scaled accordingly.
• Example:
import Image from 'example.jpg?w=200'
import Images from 'example.jpg?w=200;400;700'• Keyword: h
• Type: integer
Resizes the image to be the specified amount of pixels tall. If not given the width will be scaled accordingly.
• Example:
import Image from 'example.jpg?h=200'
import Images from 'example.jpg?h=200;400;700'• Keyword: aspect
• Type: string | number
Resizes the image to be the specified aspect ratio. Aspect ratio can be defined with a string in the form 16:9 or a
positive number representing the width divided by height (e.g., 1.5 for a 3:2 aspect ratio) If height and width are
both provided, this will be ignored. If height is provided, the width will be scaled accordingly. If width is provided,
the height will be scaled accordingly. If neither height nor width are provided, the image will be cropped to the given
aspect ratio.
• Example:
import Image from 'example.jpg?aspect=16:9'
import Image from 'example.jpg?aspect=16:9&h=200'
import Image from 'example.jpg?aspect=16:9&w=200'
import Images from 'example.jpg?aspect=16:9&h=200;400;700'• Keyword: withoutEnlargement
• Type: boolean
Prevents the image from being resized if the specified or calculated width or height are greater than the original width or height. Must be passed with a width, height or aspect directive.
• Example:
import Image from 'example.jpg?w=200;400&withoutEnlargement'
import Image from 'example.jpg?aspect=16:9&withoutEnlargement'
import Images from 'example.jpg?aspect=16:9&h=200;400;700&withoutEnlargement'• Keyword: withoutReduction
• Type: boolean
Prevents the image from being resized if the specified or calculated width or height are less than the original width or height. Must be passed with a width, height or aspect directive.
• Example:
import Image from 'example.jpg?height=300;600;900&withoutReduction'
import Image from 'example.jpg?aspect=9:16&withoutReduction'
import Images from 'example.jpg?aspect=16:9&h=200;400;700&withoutEnlargement&withoutReduction'• Keyword: rotate
• Type: integer
Rotate the image by the specified number of degrees.
NOTE: You can change the background color the empty parts are filled with by setting the background directive.
• Example:
import Image from 'example.jpg`rotate=90'
import Image from 'example.jpg`rotate=68'
import Images from 'example.jpg`rotate=90;180;270'• Keyword: tint
• Type: string
Tints the image using the provided chroma while preserving the image luminance. If the image has an alpha channel it will be untouched.
• Example:
import Image from 'example.jpg?tint=#ffaa22'
import Image from 'example.jpg?tint=rgba(10,33,127)'• Keyword: metadata | meta
• Type: boolean | string[]
Returns all information collected about the image as a JavaScript object. The directive optionally takes a list of arguments that act as a whitelist for the metadata object. You can use it to only import specific image attributes, keeping your bundle size small.
• Example:
import Image from 'example.jpg?w=500;900;1200&avif&metadata'
import { height, format } from 'example.jpg?w=700&format=gif&as=meta:height;format'• Keyword: picture
• Type: boolean
Returns information about the image necessary to render a picture tag as a JavaScript object.
• Example:
import picture from 'example.jpg?w=500;900;1200&format=avif;webp;jpg&as=picture'
let html = '<picture>';
for (const [format, images] of Object.entries(picture.sources)) {
html += `<source srcset={images.map((i) => `${i.src}`).join(', ')} type={'image/' + format} />`;
}
html += `<img src={picture.img.src} /></picture>`• Keyword: source
• Type: boolean
Returns information about the image necessary to render a source tag as a JavaScript object. This only takes the image width into consideration.
• Example:
import avif from 'example.jpg?w=500;900;1200&format=avif&as=source'
import webp from 'example.jpg?w=500;900;1200&format=webp&as=source'
import fallback from 'example.jpg?w=700'
const html = `<picture>
<source srcset="${avif.map(({src, w}) => `${src} ${w}w`).join(',')}" type="image/avif" />
<source srcset="${webp.map(({src, w}) => `${src} ${w}w`).join(',')}" type="image/webp" />
<img src="${fallback}" />
</picture>• Keyword: srcset
• Type: boolean
Returns a srcset string of the generated images to be used in a <picture> tag. This only takes the image width into consideration.
• Example:
import avif from 'example.jpg?w=500;900;1200&format=avif&as=srcset'
import webp from 'example.jpg?w=500;900;1200&format=webp&as=srcset'
import fallback from 'example.jpg?w=700'
const html = `<picture>
<source srcset="${avif}" type="image/avif" />
<source srcset="${webp}" type="image/webp" />
<img src="${fallback}" />
</picture>
`• Keyword: url
• Type: boolean
Returns a URL to the generated image. This is the default when your directives produce only one output image.
• Example:
import Image from 'example.jpg?w=500' // the type of Image is a string and it's a URL to the transformed image• Keyword: inline
• Type: boolean
Return base64 encoded inline image instead of URL to the generated image. This can be combined with some output directives like srcset or picture.
• Example:
import inlineImage from 'example.jpg?format=webp&inline';The returned inlineImage will start with data:image/webp;base64,...