# Resize images

> Change image dimensions: proportional resize, crop, pad, and smart crop.

All examples below use this original image: <https://demo.bitiful.com/girl.jpeg>

## Parameters

| Parameter | Meaning                                                                               |  Default | Values                                               |
| :-------- | ------------------------------------------------------------------------------------- | :------: | ---------------------------------------------------- |
| `w`       | **Target width**                                                                      |     –    | Pixels (up to 10000), or a percentage such as `50%`  |
| `h`       | **Target height**                                                                     |     –    | Same as above                                        |
| `dpr`     | **Additional scale factor**; the target width and height are multiplied by this value |     1    | Greater than 0, up to 10                             |
| `mode`    | **Resize mode**; see the table below                                                  |  `crop`  | `crop` / `clip` / `fill` / `scale` / `adapt`         |
| `pos`     | **Position to keep when cropping**; see below                                         | `center` | A preset position, custom coordinates, or smart crop |
| `fill`    | **Padding method**; applies only when `mode=fill`                                     |  `solid` | `solid` / `blur` / `dominant` / `auto`               |
| `bg`      | **Background color** used for padding                                                 |   White  | Hex color                                            |

In URLs, write `%` as `%25`, for example `w=50%25`.

### Resize modes

| mode    | Behavior                                                                          | Output size          |
| :------ | --------------------------------------------------------------------------------- | -------------------- |
| `crop`  | Resizes proportionally, then **crops off the excess**                             | Exactly w × h        |
| `clip`  | Resizes proportionally to fit within a w × h box, **without cropping**            | No larger than w × h |
| `fill`  | Resizes proportionally to fit within the box, then **pads** to the target size    | Exactly w × h        |
| `scale` | **Stretches** to the target size without preserving the aspect ratio              | Exactly w × h        |
| `adapt` | Chooses automatically: uses `crop` when little would be cropped, otherwise `fill` | Exactly w × h        |

- If you specify only one of `w` or `h`, the image is always resized proportionally.
- If you specify both `w` and `h` without `mode`, `crop` is used.

### Padding methods

When `mode=fill`, `fill` determines what fills the empty area:

| fill       | Effect                                                                                                                           |
| :--------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `solid`    | The solid color set by `bg`                                                                                                      |
| `blur`     | An enlarged, blurred copy of the original image as the background                                                                |
| `dominant` | The dominant color of the original image                                                                                         |
| `auto`     | Content-aware: extends the edges naturally when they are a solid color or a smooth gradient; otherwise uses a blurred background |

### Crop position

When `mode=crop`, `pos` determines which part of the image to keep.

| Form                   | Values                                                                                                                |
| :--------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Nine-grid**          | `top-left`, `top`, `top-right`, `left`, `center`, `right`, `bottom-left`, `bottom`, `bottom-right`                    |
| **Offset from center** | `top-center`, `bottom-center`, `left-center`, `right-center`: starts from the center and shifts toward that direction |
| **Custom coordinates** | `x,y`, each 0 to 1 or 0% to 100%, such as `0.25,0.75`                                                                 |
| **Smart crop**         | `smart` (`face` and `auto` are equivalent)                                                                            |

### Smart crop

`pos=smart` detects **faces, people, cats and dogs, and salient subjects** in the image and automatically picks the crop window that keeps them most intact. When faces are present, it places them naturally toward the upper part of the frame.

- Detection runs only when the aspect ratios of the original and the target differ by more than 25%; otherwise the image is center-cropped.
- Animated images are not analyzed and are center-cropped.

> **Tip**
>
> We recommend `pos=smart` whenever you need to crop images of varying aspect ratios to a uniform ratio, such as avatars, product images, and feed covers.

## Examples

<details>
<summary>Demo: width only, w=200, proportional resize</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200`**](https://demo.bitiful.com/girl.jpeg?w=200)

![Resized proportionally to 200 px wide](https://demo.bitiful.com/girl.jpeg?w=200)

</details>

<details>
<summary>Demo: height only, h=200, proportional resize</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`h=200`**](https://demo.bitiful.com/girl.jpeg?h=200)

![Resized proportionally to 200 px high](https://demo.bitiful.com/girl.jpeg?h=200)

</details>

<details>
<summary>Demo: both w=200 & h=200 (default mode=crop, pos=center)</summary>

![How cropping works](https://demo.bitiful.com/static/docs/crop-mode-demo-1.png?w=200\&fmt=webp\&q=90)

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200)

![Center crop](https://demo.bitiful.com/girl.jpeg?w=200\&h=200)

</details>

<details>
<summary>Demo: w=200 & h=200, mode=clip fits proportionally within the box</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & mode=clip`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&mode=clip)

![Fit proportionally within the box](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&mode=clip)

</details>

<details>
<summary>Demo: w=200 & h=200, dpr=0.5 outputs 100 × 100</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & dpr=0.5`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&dpr=0.5)

![Scale factor 0.5](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&dpr=0.5)

</details>

<details>
<summary>Demo: w=200 & h=200, pos=top keeps the top</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=top`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=top)

![Keep the top](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=top)

</details>

<details>
<summary>Demo: w=200 & h=200, pos=bottom keeps the bottom</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=bottom`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=bottom)

![Keep the bottom](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=bottom)

</details>

<details>
<summary>Demo: w=200 & h=200, pos=smart smart crop</summary>

URL: [https://demo.bitiful.com/girl.jpeg? **`w=200 & h=200 & pos=smart`**](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=smart)

![Smart crop](https://demo.bitiful.com/girl.jpeg?w=200\&h=200\&pos=smart)

</details>

<details>
<summary>Demo: w=300 & h=200, mode=fill padded with a blurred background</summary>

URL:

<https://demo.bitiful.com/girl.jpeg?w=300&h=200&mode=fill&fill=blur>

</details>
