> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# Next.js Image Loader and Component

> Optimize images with Uploadcare on the fly by using the Uploadcare Image component or the uploadcareLoader custom image loader for Next.js.

Optimize images with Uploadcare on the fly by using the `UploadcareImage`
component or  the `uploadcareLoader` custom image loader for Next.js.

The built-in Next.js Image component does a great job in optimizing images but
the number of optimizations is limited. It allows setting a custom image loader
to process images externally. This is where the `@uploadcare/nextjs-loader`
package comes in handy.

[GitHub →](https://github.com/uploadcare/nextjs-loader)

Here is a [demo](https://uploadcare-nextjs-loader.vercel.app) app and its
[source code](https://github.com/uploadcare/nextjs-loader/tree/main/example).

## Features

* Optimize image characteristics (quality, resolution, format, and others) with
  an extended list of Uploadcare [image processing operations](/docs/transformations/image/#image-transformations-list).
* Load the optimized images through [Uploadcare CDN](/docs/delivery/).

## Installation

```
yarn add @uploadcare/nextjs-loader
```

## Configuration

Get your [public key](/docs/start/settings/#keys-public) from the
[Dashboard](https://app.uploadcare.com/accounts/settings/) and add it to your environment variables through
`.env` file or your hosting UI.

```js
# .env
NEXT_PUBLIC_UPLOADCARE_PUBLIC_KEY="YOUR_PUBLIC_KEY"
```

If you're using a proxy, provide your application's base URL (also
whitelisted), which is required to process local images properly.

```js
# .env
NEXT_PUBLIC_UPLOADCARE_APP_BASE_URL="https://your-domain.com/"
```

Image transformation settings example:

```js
# .env
NEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS="quality/lightest, stretch/off, progressive/yes"
```

The default image transformation parameters are `stretch/off, progressive/yes`.

Find additional settings, such as custom CDN domain, and custom proxy domain,
in the developer documentation on [Github](https://github.com/uploadcare/nextjs-loader).

## Usage

Allow custom image loaders through `next.config.js`:

```js
// next.config.js
module.exports = {
  images: {
    loader: "custom"
  }
}
```

The easiest and the most straightforward way of utilizing the power of
Uploadcare is to use the `UploadcareImage` component for all images on your
site the same way as the built-in `Image` component.

```js
import UploadcareImage from '@uploadcare/nextjs-loader';

<UploadcareImage
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
/>
```

If you still need to use the built-in Image component with the
`uploadcareLoader`:

```js
import Image from 'next/image';
import { uploadcareLoader } from '@uploadcare/nextjs-loader';

<Image
  alt="A test image"
  src="https://your-domain/image.jpg"
  width="400"
  height="300"
  loader={uploadcareLoader}
/>
```

Note that if you pass a local image URL, the loader returns it AS IS if the app
is run in the development mode or if the `NEXT_PUBLIC_UPLOADCARE_APP_BASE_URL`
is not set.

## Full documentation

Read the full documentation on [GitHub](https://github.com/uploadcare/nextjs-loader).