diff --git a/docs/api-resize.md b/docs/api-resize.md
index f6d96bbdf..ed70c7f56 100644
--- a/docs/api-resize.md
+++ b/docs/api-resize.md
@@ -2,7 +2,7 @@
Resize image to `width`, `height` or `width x height`.
When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
-- `cover`: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit.
+- `cover`: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
- `contain`: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
- `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
- `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
@@ -42,18 +42,18 @@ Previous calls to `resize` in the same pipeline will be ignored.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
-| [width] | number
| | pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height. |
-| [height] | number
| | pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width. |
+| [width] | number
| | How many pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height. |
+| [height] | number
| | How many pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width. |
| [options] | Object
| | |
-| [options.width] | String
| | alternative means of specifying `width`. If both are present this takes priority. |
-| [options.height] | String
| | alternative means of specifying `height`. If both are present this takes priority. |
-| [options.fit] | String
| 'cover'
| how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. |
-| [options.position] | String
| 'centre'
| position, gravity or strategy to use when `fit` is `cover` or `contain`. |
+| [options.width] | number
| | An alternative means of specifying `width`. If both are present this takes priority. |
+| [options.height] | number
| | An alternative means of specifying `height`. If both are present this takes priority. |
+| [options.fit] | String
| 'cover'
| How the image should be resized/cropped to fit the target dimension(s), one of `cover`, `contain`, `fill`, `inside` or `outside`. |
+| [options.position] | String
| 'centre'
| A position, gravity or strategy to use when `fit` is `cover` or `contain`. |
| [options.background] | String
\| Object
| {r: 0, g: 0, b: 0, alpha: 1}
| background colour when `fit` is `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency. |
-| [options.kernel] | String
| 'lanczos3'
| the kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load. |
-| [options.withoutEnlargement] | Boolean
| false
| do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. |
-| [options.withoutReduction] | Boolean
| false
| do not reduce if the width *or* height are already greater than the specified dimensions, equivalent to GraphicsMagick's `<` geometry option. |
-| [options.fastShrinkOnLoad] | Boolean
| true
| take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension. |
+| [options.kernel] | String
| 'lanczos3'
| The kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load. |
+| [options.withoutEnlargement] | Boolean
| false
| Do not scale up if the width *or* height are already less than the target dimensions, equivalent to GraphicsMagick's `>` geometry option. This may result in output dimensions smaller than the target dimensions. |
+| [options.withoutReduction] | Boolean
| false
| Do not scale down if the width *or* height are already greater than the target dimensions, equivalent to GraphicsMagick's `<` geometry option. This may still result in a crop to reach the target dimensions. |
+| [options.fastShrinkOnLoad] | Boolean
| true
| Take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension. |
**Example**
```js
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 2c6aa585d..d5dbb0be6 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -764,7 +764,7 @@ declare namespace sharp {
* @throws {Error} Invalid parameters
* @returns A sharp instance that can be used to chain operations
*/
- resize(width?: number | null, height?: number | null, options?: ResizeOptions): Sharp;
+ resize(widthOrOptions?: number | ResizeOptions | null, height?: number | null, options?: ResizeOptions): Sharp;
/**
* Shorthand for resize(null, null, options);
diff --git a/lib/resize.js b/lib/resize.js
index aa7a22a76..41001f9af 100644
--- a/lib/resize.js
+++ b/lib/resize.js
@@ -118,7 +118,7 @@ function isResizeExpected (options) {
* Resize image to `width`, `height` or `width x height`.
*
* When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
- * - `cover`: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit.
+ * - `cover`: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
* - `contain`: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
* - `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
* - `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
@@ -231,32 +231,32 @@ function isResizeExpected (options) {
* .toBuffer()
* );
*
- * @param {number} [width] - pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
- * @param {number} [height] - pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
+ * @param {number} [width] - How many pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
+ * @param {number} [height] - How many pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
* @param {Object} [options]
- * @param {String} [options.width] - alternative means of specifying `width`. If both are present this takes priority.
- * @param {String} [options.height] - alternative means of specifying `height`. If both are present this takes priority.
- * @param {String} [options.fit='cover'] - how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`.
- * @param {String} [options.position='centre'] - position, gravity or strategy to use when `fit` is `cover` or `contain`.
+ * @param {number} [options.width] - An alternative means of specifying `width`. If both are present this takes priority.
+ * @param {number} [options.height] - An alternative means of specifying `height`. If both are present this takes priority.
+ * @param {String} [options.fit='cover'] - How the image should be resized/cropped to fit the target dimension(s), one of `cover`, `contain`, `fill`, `inside` or `outside`.
+ * @param {String} [options.position='centre'] - A position, gravity or strategy to use when `fit` is `cover` or `contain`.
* @param {String|Object} [options.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour when `fit` is `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency.
- * @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load.
- * @param {Boolean} [options.withoutEnlargement=false] - do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option.
- * @param {Boolean} [options.withoutReduction=false] - do not reduce if the width *or* height are already greater than the specified dimensions, equivalent to GraphicsMagick's `<` geometry option.
- * @param {Boolean} [options.fastShrinkOnLoad=true] - take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension.
+ * @param {String} [options.kernel='lanczos3'] - The kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load.
+ * @param {Boolean} [options.withoutEnlargement=false] - Do not scale up if the width *or* height are already less than the target dimensions, equivalent to GraphicsMagick's `>` geometry option. This may result in output dimensions smaller than the target dimensions.
+ * @param {Boolean} [options.withoutReduction=false] - Do not scale down if the width *or* height are already greater than the target dimensions, equivalent to GraphicsMagick's `<` geometry option. This may still result in a crop to reach the target dimensions.
+ * @param {Boolean} [options.fastShrinkOnLoad=true] - Take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension.
* @returns {Sharp}
* @throws {Error} Invalid parameters
*/
-function resize (width, height, options) {
+function resize (widthOrOptions, height, options) {
if (isResizeExpected(this.options)) {
this.options.debuglog('ignoring previous resize options');
}
- if (is.defined(width)) {
- if (is.object(width) && !is.defined(options)) {
- options = width;
- } else if (is.integer(width) && width > 0) {
- this.options.width = width;
+ if (is.defined(widthOrOptions)) {
+ if (is.object(widthOrOptions) && !is.defined(options)) {
+ options = widthOrOptions;
+ } else if (is.integer(widthOrOptions) && widthOrOptions > 0) {
+ this.options.width = widthOrOptions;
} else {
- throw is.invalidParameterError('width', 'positive integer', width);
+ throw is.invalidParameterError('width', 'positive integer', widthOrOptions);
}
} else {
this.options.width = -1;